aster-cli

name	aster-cli
description	Guidance for using the `aster` CLI to work in a codebase with an AI agent: chat and edit code, run AI code reviews, apply fixes, and manage sessions, memory, and skills. Use when running or designing aster commands, reviewing a diff or PR with aster, or when the user mentions `aster review`, `aster chat`, `aster fix`, or aster.yaml.

Aster CLI

Aster is an AI coding agent that works in your repository: it reads and searches the code, answers questions, applies edits, and runs a review pipeline that forms hypotheses about defects, verifies them against the codebase, and reports shaped findings. It runs locally against the current repo and needs an aster.yaml (created by aster init).

Setup

aster init          # pick a provider, write aster.yaml, store the API key
aster login         # optional: link GitHub via device flow (needed for PR reviews)

aster init is interactive. Run it once per repo; keys are stored outside the repo so aster.yaml is safe to commit.

Reviewing code

aster review                    # review the current branch against its base
aster review main..HEAD         # review an explicit range
aster review path/to/file.rs    # review a single file
aster review --pr 123           # review a GitHub PR (requires aster login)

Review output is a list of findings. Prefer reviewing the smallest meaningful diff: a branch or range, not the whole repo.

Chat and fixes

aster chat                      # interactive TUI with the review agent
aster chat --print "question"   # one-shot answer to stdout (use this from scripts and agents)
aster fix                       # apply model-generated fixes for findings (dry-run by default)

As an agent, always use aster chat --print rather than the TUI. aster fix never writes without an explicit apply flag; run it plain first and inspect the dry-run output.

Sessions and memory

aster sessions                  # list saved chat sessions for this repo
aster sessions show <id>        # print a session's full transcript
aster memory                    # list stored durable memory
aster memory add "fact"         # append a fact to project memory
aster memory add --title t "…"  # save a titled memory block

Both accept --json; see below.

Skills

Aster loads agent skills from .aster/skills (project) and <config>/aster/skills (user-global).

aster skills add owner/repo     # install skills from a GitHub repo (also: git URL or local path)
aster skills add -g owner/repo  # install user-global instead of project
aster skills add owner/repo -l  # list what a source offers without installing
aster skills list               # list installed skills
aster skills use owner/repo@x   # print a skill's instructions without installing
aster skills find <query>       # search GitHub for skills interactively
aster skills update             # update all installed skills
aster skills remove <name>      # remove a skill
aster skills init <name>        # scaffold <name>/SKILL.md

add flags: -s/--skill to pick specific skills (* for all), --all for everything without prompts, -y to skip confirmation, --force to overwrite, --full-depth to keep searching inside a directory that already has a SKILL.md.

Machine-readable output

--json is global: every command takes it, before or after the subcommand, and prints one JSON value on stdout. Failures come back the same way, {"ok":false,"error":"…"} with a non-zero exit, so a caller parses one shape.

aster --json sessions list
aster --json skills list
aster --json memory add "fact"
aster review --json

--json also forces non-interactive behavior: wizards and prompts are skipped, so a command either completes or errors instead of hanging.

Modes and effort

How the agent is allowed to act (--permission-mode on aster chat, or permissions.mode in aster.yaml):

• plan — explore and present a plan, never edit
• manual — ask for approval before each edit (needs the TUI or --stream)
• auto — apply what passes the safety check, pause for anything risky
• edit — edit files without asking (the default)

--effort <off|low|medium|high> sets the reasoning budget for thinking models on chat, aster review, and aster fix, overriding ASTER_EFFORT and review.effort in aster.yaml. In the TUI, /mode cycles modes and /effort sets the budget.

Conventions

• Non-interactive contexts (CI, agents): use --print, --json, and -y variants; never invoke the TUI.
• Every command supports --help; check it before guessing flags.
• Before editing aster.yaml, check docs/CONFIG.md for the key and its default. Unknown keys are a hard parse error, not a warning.