CLI reference

The aachat CLI splits its roles across three binaries. Which binary to point to is determined by where the user (or agent) is.

Each command's --help is the source of truth for arguments. This page summarizes what was confirmed against the installed CLI's --help and the code. If your CLI is older, update it with aachat update, then check aachat --version and the command's --help.

Output format

aachat

Project selectors in aachat accept either a name or <team>/<project>. For example, aachat find --project team/project selects the same target as aachat find --project project --team team. If a qualified Team conflicts with --team or another Project selector in the same command, the CLI rejects the input before any request (conflicting_arguments, exit 2). Empty selectors, empty parts, and multiple slashes are invalid (invalid_argument, exit 2). Bare names retain the command’s existing search scope or connected-repository Team resolution; AA_TEAM is not a new default. For project create, the new Project name is still a name definition; only --parent is a selector. Session sends using a qualified selector require the corresponding server support as well as the updated CLI.

Nearly every command returns one JSON envelope on stdout: {"ok": true, "data": {...}} on success, {"ok": false, "error": {"code": ..., "message": ...}} on failure, optionally with warnings and next_actions. Read next_actions when present. aachat tag list --json is the exception to the default text output for the vocabulary command. --help and --version output is text.

Only these four do not return a JSON envelope:

Exit status is 0 for success, 1 for an execution failure, and 2 for a missing or invalid argument. An exit code of 0 does not turn a failed/skipped diagnostic into a healthy result: read the status fields and each check in doctor --view checks.

Lists default to 20 items with a maximum of 100. Continue with data.next_page; read an individual body with detail_read. Both are command locators ({"kind": "command", "program": ..., "argv": [...]}): run argv with program as-is, without joining it into a shell string (pagination).

Commands that read a body (project read --message, project document --path, ask show, db schema, and others) return a preview. Use these only when you need the whole text:

Inside an Agent Session (the AA_SESSION_ID environment variable is set), aachat refuses these human-scoped operations with invalid_argument. Where one exists, next_actions points to the matching chat command or to running the command outside the Session; some refusals (such as project ensure and Lead changes) return only the message: ask answer / ask cancel, db, trigger, workflow, skill feedback, session permission / schedule / compact, and project ensure, content catalogs, message mutations, delete / reparent / assign / unassign, and Lead changes or --cancel-runs, among others. Inside a Session, aachat session list row references point to chat session show <id> --project <team>/<project>, and outside-only views such as session read --decision are refused.

chat

Every ordinary chat command returns one JSON object on stdout:

• Success: {"ok": true, "data": {...}}
• Failure: {"ok": false, "error": {"code": ..., "message": ..., ...}, "data": {...}} (data only when there is a partial result)

Exit status is 0 for success, 1 for an execution failure, and 2 for invalid input or arguments. A failure's error can include the target project or field, candidates, runnable next commands (an array of command locators), and a hint. --help and --version output is text and exits successfully. ok: true means the command was accepted; it does not mean a Session or Run succeeded.

Lists return data.next_page (null at the end) and each item's detail_read as command locators {"kind": "command", "program": "chat", "argv": [...]}. Run argv as an array. A path locator with base: workspace resolves from AA_WS_DIR. Do not treat truncated or an unread continuation as empty.

chat runs within the session's scope, so it has no --team flag. Select the Project as each command's help describes; --project takes <team>/<project> or a project slug. A Project outside the current session's authority is rejected.

Authentication, diagnostics, updates

aachat auth login                # Issue and cache a short-lived JWT from local gh auth (~/aachat/.run/tokens/user.jwt)
aachat auth status               # Check sign-in state
aachat auth logout               # Delete stored credentials
aachat status                    # Current connection (repo and Team), auth, daemon, and projection state (no Launch Report)
aachat doctor [--view checks]    # Bounded read-only checks of workspaces, projections, and shared dependencies
aachat update                    # Update aachat itself

If gh is authenticated, auth login completes non-interactively (Trust Boundary).

For problems, start aachat support. doctor is the diagnostic API used by support and other agents.

doctor runs read-only checks with per-check deadlines and output limits, returning one JSON object on stdout. The default data.diagnostics.issues contains non-pass entries; --view checks returns all entries in checks, and counts always counts all entries. Each check includes id, required, state, reason, category (blocker, preservation, maintenance, or information), code, target, observed_at, next_actions, and recheck. Different targets can share an id. data.observed_at is the aggregation time; synchronization fields source_observed_at, last_sync_at, and runtime_state distinguish stored observations from this inspection. Unknown capacity and artifact measurements remain null.

Workspace inspection has a 20-second budget, including a 500 ms reserve to stop and reap the worker process group. On timeout, completed per-folder findings and the latest free-space observation remain available. The root session_workspace_maintenance summary includes coverage: entries_observed, entries_reported, entries_verified, enumeration_complete, total_entries, unverified_entries, in_progress_path, identities_complete, and complete. Reported entries include errors; verified entries may include confirmed preservation failures. Totals and remaining counts are null until enumeration completes. Summary pass means classification and measurement covered the observed scope, not that there are no findings. The capacity check's filesystem_observation contains observed_at, free_bytes, and required_headroom_bytes, independently of aggregate measurement. Unfinished aggregate capacity remains null; low free space still fails the capacity check. These are sequential observations, not an atomic snapshot. Investigate the interrupted path and preserve the displayed work; repeating the full scan does not guarantee coverage.

overall is issues_found for a confirmed blocker; otherwise incomplete for any unknown check, including optional checks, or a required skipped check; otherwise attention_needed for preservation or maintenance findings; otherwise healthy. Legitimate not_applicable skips do not make the result incomplete. healthy means no findings within the checks performed; it does not verify provider authentication, model calls, or current synchronization success.

Successful diagnosis and aggregation return ok:true and exit 0 even with findings or ordinary probe timeouts. Interruption, parent execution failure, or unverified child cleanup returns ok:false and exit 1; invalid arguments exit 2. Interruption and unverified cleanup retain accepted diagnostics in data. An unfinished scan cannot establish all paths or counts. Workspace diagnostics do not evaluate active Session protection and do not authorize deletion. Preserve the target's work and follow next_actions and recheck; startup, restart, and authentication changes require human approval.

Runtime

aachat up [--if-stopped] [--events]   # Start the resident runtime
aachat launcher status                # Read the launcher's runtime state; never starts anything
aachat launcher check-ready           # Read-only check of selected-home launcher, daemon, host sync, and authenticated API within 10 seconds
aachat launcher start                 # Start the runtime once through macOS launchd (macOS only)
aachat launcher stop                  # Stop a runtime started through the launcher (macOS only)
aachat launcher request <id>          # Versioned startup request for a native launcher (used by legacy Desktop 0.x)
aachat support [--provider claude|codex] [--symptom <text>] [--receipt]            # Interactive support
aachat support recover-layout --root <absolute-aachat-root> --backup <new-backup-dir> [--apply --writers-stopped]   # Inspect the legacy layout by default; --apply preserves the old root in backup and switches after all producers stop
aachat support cleanup-retired-team-features [--inventory <absolute-json>] [--apply --writers-stopped]   # Offline inspection by default; apply removes verified retired feature data
aachat manage-agent [--receipt]       # Interactive agent management (search / clone / customize / add skills)

The cleanup command requires no authentication or network access. Inspection changes no files; apply requires all old writers and automatic restart sources to be stopped and --writers-stopped to assert that fact. Normal home, connected repositories and inactive managed Sessions are always inventoried; --inventory adds verified recovery/cutover copies. Unknown or unsafe roots remain blocked. Require complete inventory and zero remaining targets before restarting. Preserve Wiki, Project and Workflow drafts; do not replay retired edits.

aachat support requires stdin/stdout terminals and the selected CLI. The default is Claude Code; use aachat support --provider codex to select Codex explicitly (verified with CLI 0.160.0). There is no automatic fallback. Codex starts read-only with on-request human approval; --receipt also requires a stderr terminal. --symptom is optional (up to 8 KiB of UTF-8); without it, describe the problem after startup. Arguments can remain in shell history, so never include secrets. Support reads its CLI-bundled contract and initial diagnostics without fetching the Web contract. Its private temporary directory contains the contract and context (including the symptom and diagnosis), is removed after the child exits or fails to spawn, and may remain in the OS temporary directory after abnormal termination. Child exit success does not prove the problem is resolved.

aachat up owns the resident runtime. Plain up replaces and restarts an existing runtime, while up --if-stopped exits successfully without replacing one already running. It checks for updates at startup and, while running, every hour once no agent turn is active. After installing a new binary, it waits for idle again, performs the normal shutdown, and re-execs with the same arguments. A turn that starts after the idle check can still be interrupted, and a Session stopped while waiting for a human response is not resumed automatically. If it stops on a sync protocol mismatch with the server, it also updates once after the normal stop and save, and re-execs if the version changed; a human chooses how to continue Sessions interrupted midway. Inspect the Launch Report after a restart (Environment).

Individual historical Session workspace problems produce maintenance warnings and do not stop the host or unrelated Sessions. Each workspace is validated again before use; an affected Session may still fail to start or resume. Existing work is preserved, not automatically repaired or recreated. Shared-root or workspace-parent inspection failures still block startup. Read the Launch Report in up.log and run aachat doctor for current findings, or aachat support for repair guidance.

The runtime log is ~/aachat/.run/logs/up.log. It is written from the moment the daemon takes ownership and rotates at each start and every 10 MiB into up.log.1 through up.log.8. The terminal shows classified failures with a pointer to the detailed log, a summary of repeated identical failures every 60 seconds, and recovery lines. RUST_LOG applies to both the terminal and the file.

aachat launcher check-ready checks the aachat home selected by AACHAT_HOME; it never substitutes the current directory or a Session workspace mirror for host synchronization. data.readiness (schema_version: 1) contains observed_at, state (ready / preparing / blocked), reason, and checks (pass / fail / unknown for launcher, daemon, projection, and api). Only four passing checks produce ready; ok: true alone does not mean ready. It does not refresh cached authentication or return credentials or Team-list contents. Timeouts and unavailable observations remain unknown.

aachat launcher is the CLI entry point for starting and stopping the runtime through macOS launchd, and uses the same path as the legacy Desktop 0.x startup entry. On Desktop startup, the guide prepares the runtime with ordinary CLI commands such as aachat up or aachat launcher, while the app shows progress and any required user action. Desktop itself verifies readiness with launcher check-ready. launcher start starts the runtime once through macOS launchd, and the runtime keeps running after the Desktop app quits or updates. Use aachat status or aachat launcher status to check state. The internal launchd entry point service-run is hidden from --help. aachat status does not return the startup results (Launch Report); read the === Launch Report === section of up.log. Stop a runtime started with aachat up in a terminal with Ctrl+C in that terminal (Desktop).

Repo connection

aachat init [--team <slug>]   # Connect the current git repo to a team

init never waits for input. If you belong to several Teams, it returns ambiguous_team with candidates; rerun it with --team <slug>. Writes go only to files inside that repo and the local record in ~/aachat/.state/repo-connections/. Writes to paths outside the repo and writes through symlinks are rejected. Details in Connected Repo.

team

aachat team create <slug> [--repo <owner/repo>]   # Create a private team whose name equals the slug. --repo optionally sets its default workspace repo
aachat team update <slug> --stdin                 # Update explicit settings from one JSON object
aachat team join <token>                          # Join with an invitation token
aachat team list [--limit N] [--cursor <cursor>]  # List teams you belong to
aachat team show <slug> [--context]               # Team details

agent

The values accepted by --runtime are claude-acp and codex-acp.

aachat agent list [--mine] [--limit N] [--cursor <cursor>]
aachat agent show <agent> [--view config|assignments|sessions] [--limit N] [--cursor <cursor>]
aachat agent create <name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]
aachat agent ensure <name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]
aachat agent ensure <name> --source <owner/repo>
aachat agent update <name> [--repo <owner/repo>] [--dormant | --no-dormant] [--runtime claude-acp|codex-acp]
aachat agent delete <name> --yes
aachat agent search [query] [--sort popular|recent|stars] [--limit N] [--cursor <cursor>]   # Search public agents on Discover
aachat agent show-public <owner/repo> [--view readme|skills] [--full | --output <new-file>]
aachat agent clone <owner/repo> [--name <name>]   # Copy a public agent into your account

• agent create without --repo immediately creates a private agent repo from the template with GitHub CLI (gh repo create --template). The first aachat up for an Agent registered without a repo does the same. So gh must be installed and logged in. The CLI sets no display name, so the WebUI shows the handle (add one later with Edit display name)
• agent delete requests a stop and returns 409 (“The Agent still has active Sessions or Workflow Steps. … Retry Agent deletion after termination is confirmed.”) while the Agent has active Sessions or Workflow Steps. Retry after confirming they stopped. The DM Project and Session history remain after deletion
• agent clone <owner/repo> [--name <handle>] is also shown as the fallback when a clone from Web Discover fails
• agent ensure returns an existing Agent unchanged. For a missing Agent, use either --source to clone or the repo/description/runtime creation options; --source conflicts with those options
• aachat up skips an Agent put into agent update --dormant. --runtime changes the default Runtime for future Session launch drafts
• Session counts in agent show --view sessions cover owner-visible active and recently failed Sessions, not lifetime history

Environment and catalog publication and installation

aachat env                                   # Same summary as env list
aachat env --interactive                     # Interactive setup UI (cannot be combined with a subcommand)
aachat env list [--all] [--name <NAME>] [--owner <owner>] [--view summary|requesters] [--limit N] [--cursor <cursor>]
aachat env approve <agent> <NAME> [--destination local-keychain|local-env]
aachat env adopt                             # Adopt legacy local settings (interactive human terminal only)
aachat env keychain-check
aachat env default --destination local-keychain|local-env
aachat env keychain-access --name <NAME> [--name <NAME> ...] [--reauthorize]
aachat env revoke <agent> <NAME>

aachat publish <agent> [--name <text>] [--description <text>] [--tag <tag>]... [--go-public]
aachat skill publish .agents/skills/<skill-name> --agent <name> [--go-public]
aachat skill sync <catalog-id>
aachat skill unpublish <catalog-id>
aachat skill install <catalog-id> --agent <name>

aachat plugin publish (<owner/repo> | <checkout-path> --agent <name>) [--headline-ja <text>] [--headline-en <text>] [--description-ja <text>] [--description-en <text>] [--tag <key>]... [--go-public]
aachat plugin sync <owner/repo>
aachat plugin unpublish <owner/repo>
aachat plugin install <catalog-id> --agent <name>
aachat plugin remove <catalog-id> --agent <name>

env manages local name-specific approval, not secret values on the server. approve grants the Agent use of a currently requested name whose provider value exists, from the chosen destination (local-keychain is the macOS Keychain; local-env is .env). Without --destination, it asks for the destination interactively, so stdin and stdout must be terminals and it must run outside an Agent Session. Pass --destination for non-interactive use. revoke does not delete the provider value. adopt is not an access grant: when Local setup required appears, it adopts legacy local settings into the schema 2 management settings. An authenticated human runs it in an interactive terminal outside an Agent Session, checks the displayed path, owner, and permissions, and types adopt (Environment).

env keychain-check creates a disposable non-secret item, reads it in a separate helper, and deletes it after setup, authentication, and connection of the selected Mac. Use an official signed macOS release with the same explicit AACHAT_HOME and absolute aachat path. It accepts no arguments or secret input and does not change env settings or bindings. Match data.target.root_id against the WebUI computer_id. status:ready describes only this current check. Preparation failures also return status:failed and a code, with target:null before the target is known. Cleanup failure or stdout failure exits nonzero. The 30-second operation and independent 10-second cleanup budgets may require additional helper reaping time; completion within 40 seconds is not guaranteed.

env default --destination selects only a registered destination in existing schema 2 settings. A human terminal (TTY stdin/stdout, no AA_SESSION_ID) displays the root, owner, and old/new defaults and requires yes. Only the default changes; values, destination definitions, and Agent permissions are kept. Missing or legacy settings return local_setup_required; an unregistered Keychain destination returns unsupported. New Macs do not need this command. Declining or cancellation before commit leaves settings unchanged. An unknown result or output failure does not mean rollback: inspect the current default in Tools > Secrets before retrying.

Normal Keychain Save, read verification, and Allow are noninteractive. saved_unverified means saved but not verified readable; do not create the value again. Run env keychain-access --name NAME on the same Mac/root, adding --reauthorize in a human terminal only for permission_denied. Check the signature and login Keychain state without assuming that denial means a lock. Refresh the WebUI and use Allow if Agent permission still needs repair. Saved · Allowed describes registration and permission only. The new server and CLI require Secrets version 3 and do not fall back to an older version.

publish prepares or registers the Agent's reviewed publication repository. --name, --description, and --tag (repeatable) are the human-approved public profile. When omitted on first registration, it uses a valid existing .aachat/public.yaml, otherwise the Agent display name and description. Omit all of them to keep the existing profile for the same Agent and repository. Use skill publish in a separate Skill publication repository to register only the selected Skill; the source Agent does not need to be public. plugin publish lists a public GitHub repository, or a prepared publication checkout, as a Plugin. In each case, --go-public explicitly changes an already-prepared private repository's visibility. sync re-reads the public GitHub content and unpublish stops the listing; neither changes GitHub files or visibility (Discover).

skill install and plugin install record the catalog installation after the target Agent's repository change has been committed and pushed; they do not install files. plugin remove forgets the installation after the directory is removed. skills add adds local skill files and skill feedback records Skill Ledger feedback; both are separate operations (Skills).

project

project read / project send are the input/output of the timeline. The timeline returns messages, Shared Documents activity, and session activity interleaved in oldest-first order.

aachat project list [--status planning|active|completed|archived|all] [--limit N] [--cursor <cursor>] [--team <team>]
aachat project create <name> --lead <member> --stdin [--parent <parent>] [--description <text>] [--team <team>]   # Name is [a-z0-9-], 2-30 characters
aachat project ensure <name> --lead <member> --stdin [--description <text>] [--team <team>]
aachat project update <name> [--description <text>] [--status planning|active|completed|archived] [--cancel-runs] [--team <team>]
aachat project update <name> --lead <member> [--team <team>]
aachat project reparent <child> --parent <parent> --stdin [--team <team>]
aachat project delegations <parent> [--limit N] [--cursor <cursor>] [--team <team>]
aachat project delete <name> --yes [--team <team>]
aachat project show <name> [--context] [--team <team>]   # --context: entry points for continuing work
aachat project members <name> [--agent <agent>] [--view sessions] [--limit N] [--cursor <cursor>] [--team <team>]
aachat project join <name> [--team <team>]
aachat project read <project> [--last N] [--before <cursor>] [--team <team>]
aachat project read <project> --message <seq> [--full | --output <new-file>] [--team <team>]
aachat project read <project> --after-seq <seq> [--team <team>]
aachat project send <project> (<msg> | --stdin) [--reply-to <seq>] [--via <label>] [--type <type>] [--attach <path>]... [--team <team>]
aachat project edit <project> <seq> (<text> | --stdin) [--team <team>]
aachat project unsend <project> <seq> [--team <team>]
aachat project post-type update <project> <seq> --type <type> [--team <team>]
aachat project assign <project> --agent <name> [--team <team>]
aachat project unassign <project> --agent <name> [--team <team>]
aachat project document <project> [--limit N] [--cursor <cursor>] [--team <team>]              # Shared Documents catalog
aachat project document <project> --path docs/<file> [--full | --output <new-file>] [--team <team>]
aachat project document <project> --view templates [--team <team>]                              # The Project kind's template sources
aachat project media <project> [--query <text>] [--id <media-id>] [--limit N] [--before <cursor>] [--team <team>]
aachat project html <project> [--path <path>] [--view files|content|dependencies] [--limit N] [--cursor <cursor>] [--team <team>]
aachat project database <project> [--limit N] [--cursor <cursor>] [--team <team>]   # Read the schema catalog. Changes use chat db inside a Session

• --type values are chat, idea, hypothesis, issue, task, question, report, and decision, for root posts only
• project send --attach attaches an image, video, or PDF to the timeline message. It is not published to Project Media
• project read --message <seq> reads one message body; --after-seq <seq> returns messages newer than that seq, oldest first
• project document --path takes a projected path that starts with docs/. If the Project exists but the document is not yet synced or published, it returns not_found (field: path) with next_actions listing published documents and aachat status
• project update --lead cannot be mixed with other changes. --cancel-runs works only with --status archived and cannot be combined with description or Lead changes
• project delete is allowed for Project Admins (human or agent) from any status: planning, active, completed, or archived. It is refused during an Archive and while child Projects remain (Projects)
• project show returns the Project ID as data.project.id, including inside a Session (chat project info does not return a Project ID)

Entering an existing Project: run aachat project show <name> --team <team> --context. project.lead is the current Lead (returned with or without --context). project.context.documents lists PROJECT.md and REPORT.md with state, title, a summary preview and, when present, a detail_read; project.context.links gives a detail_read for each related list.

create requires a Lead and a Brief from stdin. The description is an optional catalog note, not a replacement for the Brief. For example, write the goal, background, expected deliverables, and constraints in brief.md, then run aachat project create first-project --lead @<owned-agent> --stdin < brief.md (replace <owned-agent> with the actual name of an agent you own). Names stream, dm, and repo are reserved. An agent Lead receives an ongoing dialogue Session; a human Lead receives a notification. For an agent Lead, open the Project’s Lead tab, select a proposed request or reply freely, and answer questions from the assigned agents. A human Lead uses the notification to review the Project and Brief and begin the work. See Projects for parent and ownership conditions and the REPORT required at completion.

Ensure a Project without duplicating the setup request

Both create and ensure require --lead and --stdin. create creates a new Project; ensure returns an existing one unchanged, with created: false, rather than replacing its Brief or Lead. The flags are still required for parsing when it exists.

cat > brief.md <<'BRIEF'
Purpose: Prepare a bilingual customer guide.
Background: Readers need to complete their first task without missing prerequisites.
Expected result: A guide draft and a record of the examples checked.
Constraints: Use current supported features; do not publish yet.
BRIEF
aachat project ensure first-guide --lead @<active-team-member> --team <team> --stdin < brief.md
aachat project show first-guide --team <team>

Replace <active-team-member> and <team> with real values. ensure can create a missing Project only with an active Team member as Lead. Inspect created before sending work again; this command does not return the accepted Lead action. If it created the Project, use project show and the Project timeline to inspect current state. For an existing Project, read its current purpose and members before making a separate request. Lead changes, child REPORT reads, and full reparent Brief steps are in Projects.

Archive a Project

As a Project Admin, check the target Team and Project before running the command. Archive cannot be sent together with description or Lead changes.

aachat project update <name> --status archived --team <team>

In an interactive terminal, read the Run cancellation counts, Sessions to stop, and blockers before answering the confirmation. In non-interactive use, --cancel-runs is required when unfinished Runs exist, as explicit consent to cancel them. Do not add it as a general workaround for errors. A non-interactive request without unfinished Runs may be accepted without this flag.

A returned archive_in_progress means the operation was accepted, not completed. Archive is asynchronous: it cancels unfinished Runs and waits for Sessions to stop. Completion is distinguished by archived and operation.completed_at. If an operation already exists, running the same command again returns its state. To resume a failed operation, use Retry in the WebUI (recovery steps). The in-Session chat project update has no such flag.

ask

Read, answer, or cancel existing Project Asks. Session agents create and wait with chat ask. External agents ask the human in their own conversation with their host's ask.

An Ask is immutable, and answers accumulate as revisions. show returns the latest answer and expected_revision (the latest saved answer revision, 0 when unanswered; state_version is a different counter). Pass it to answer --expected-revision. On a mismatch answer saves nothing and fails with conflict: data.ask is the current Ask and error.message names the value to rerun with. If data.ask.latest_answer is present, show that answer to the human before rerunning.

aachat ask list <project> [--status open|answered|cancelled|all] [--scope project|session] [--assignee <@user>] [--creator <@user> | --mine] [--limit N] [--before <cursor>] [--team <team>]
aachat ask show <project> <ask-id> [--view decision|answers|answer|cancellation] [--answer-revision N] [--before-revision N] [--limit N] [--full | --output <new-file>] [--team <team>]
aachat ask cancel <project> <ask-id> --reason <text> [--via <label>] [--team <team>]
aachat ask answer <project> <ask-id> --expected-revision <N> (--answer <text> | --stdin) [--via <label>] [--team <team>]

• ask list defaults to status open
• show --view answers pages every revision, newest first; go back with --before-revision. --view answer --answer-revision N returns one revision
• --via (on ask answer / ask cancel and session permission respond) is a self-reported label for an external agent's tool name. It does not replace the authenticated principal

Exploring context

Team policies, structure, and meeting notes live in Team Wiki. Read aachat/teams/<team>/wiki/README.md, find relevant pages, and follow _sync.md / _errors.md to confirm saves.

aachat inbox [project] [--mark] [--last N] [--before <cursor>] [--with-messages] [--message-limit N] [--team <team>]
aachat find [query] [--project <project>] [--by <name>] [--mentioning <name>] [--last N] [--before <cursor>] [--team <team>]
aachat mentions [project] [--last N] [--before <cursor>] [--team <team>]

• inbox returns summaries of Projects with unread items. --last defaults to 20 and --message-limit (with --with-messages) defaults to 5 (max 5). Continue Project summaries with --before; read message bodies with project read. --mark marks the returned Projects as read
• find requires a query or at least one of --project / --by / --mentioning. The scope is projects and DMs (Streams are excluded). --by / --mentioning take a visible member's exact name; agents use <agent>.<owner>
• For a query search, each result body is an excerpt of at most 240 characters around the match, with … where text was cut. To read the whole message, execute the returned detail_read using its program and argv unchanged.
• find excludes the first user prompt of a Session started by a Trigger. It does not exclude ordinary human posts or the first message of every Session, and the exclusion does not apply to mentions. If a launch instruction is missing from search, open the target Session's transcript (Sessions)

session

aachat session list [--agent <name>] [--project <project>] [--last N] [--before <cursor>] [--team <team>]
aachat session run <agent> --project <project> [--repo <owner/repo>] [--runtime claude-acp|codex-acp] [--config <ID=id:VALUE|ID=boolean:BOOL>]... [--attach <path>]... [<msg> | --stdin] [--team <team>]
aachat session send <session-id> --project <project> [--cancel-current-turn] [--attach <path>]... [<msg> | --stdin] [--team <team>]
aachat session read <session-id> --project <project> [--last N] [--before <cursor>] [--team <team>]
aachat session read <session-id> --project <project> --decision [--team <team>]
aachat session read <session-id> --project <project> --submission <turn-id> [--view results|evidence] [--team <team>]
aachat session read <session-id> --project <project> --view pending|children|results [--limit N] [--cursor <cursor>] [--team <team>]
aachat session read <session-id> --project <project> (--message <id> | --result <id>) [--full | --output <new-file>] [--team <team>]
aachat session stop <session-id>    # Immediate termination. The running turn may be interrupted
aachat session logs <session-id> [--from-start | --after-offset N] [--lines N] [--generation N] [--host <host>]
aachat session permission list <session-id> --project <project> [--request <request-id>] [--limit N] [--cursor <cursor>] [--team <team>]
aachat session permission respond <session-id> <request-id> --project <project> (--option-id <id> | --cancel) [--via <label>] [--team <team>]
aachat session schedule create <session-id> --project <project> --at <RFC3339> [--every <60-86400 seconds>] (<prompt> | --stdin) [--team <team>]
aachat session schedule list <session-id> --project <project> [--schedule <schedule-id>] [--view summary|content|history] [--limit N] [--cursor <cursor>] [--team <team>]
aachat session schedule cancel <session-id> <schedule-id> --project <project> [--team <team>]
aachat session compact <session-id> --project <project> [--request-id <uuid>] [--team <team>]

• run always starts a new session. The agent is resolved as a member of the project
• session list without --project is the Team Work Index: every readable project in the connected team, all lifecycles, including other members' sessions. --project narrows it to one project. Each session returns its affiliated project and also_covers only when there is extra coverage. --last defaults to 10 (max 100). Row text and failure reasons are 100-character previews; read the full text through the returned detail reference
• Each row's attention.items[].code lists only the mechanical reasons that need a person, in this order: permission_pending (a permission request is waiting), submission_pending (a submission is pending), and failure (the Session failed). Each row also returns attention.count and attention.has_more; a non-empty attention.items list needs action
• --repo specifies the working repository. --runtime selects this Session's Runtime. When both Runtime and config are omitted, resolution follows Agents. Repeat --config for explicit Runtime settings, for example --config mode=id:plan
• --attach attaches images, videos, and PDFs to the session history. They are not published to Project Media. run / send may be attachment-only, with no text
• --cancel-current-turn is a strong operation that discards the running turn and injects a new instruction. Use it only for changing direction or correcting a mistaken execution
• read and logs form a pair: session read reads the transcript stored on the server, session logs reads the local agent stderr log (~/aachat/.run/logs/, 100 lines by default). logs does not accept --project. For where session records live, see Trust Boundary
• session read --decision returns a bounded decision view. --submission <turn-id> tracks one accepted turn. The two are mutually exclusive. Examples and turn-ID interpretation are in Sessions
• session schedule creates, lists, or cancels a scheduled follow-up on an existing session. Fresh-Session / Workflow Triggers use aachat trigger, chat trigger, or the WebUI (Triggers)
• session compact queues compaction for a project-scoped session. It does not finish the session
• session permission list|respond reads and answers runtime Permission requests. Any human member of an active Project covered by the Session can respond

Document validation, skills, Workflows, Triggers, Database

aachat doc check <path>            # Validate one projected shared document file without network access
aachat doc check --hook            # Read a runtime hook payload from stdin (managed Session only)
aachat skills add <name> [--target <dir>] [--skill <name>]...   # Add a local skill under <target>/.agents/skills/ (thin wrapper around npx skills add)
aachat skill feedback <skill-name> (<feedback> | --stdin) [--location <text>] [--suggestion <text>] [--team <team>]   # Human feedback for an active Skill Ledger skill

• doc check validates a file in a Session workspace, under ~/aachat/teams/<team>/projects/<project>, or in an aachat init connected repository. Otherwise it returns repo_not_connected
• doc check --hook blocks a write with exit status 2 only for rejecting diagnostics. Warnings come back as additional context and do not block. If the hook cannot inspect a write, it says the file was written unchecked and suggests updating aachat

aachat workflow create <project> <slug> --client-nonce <uuid> [--team <team>]
aachat workflow draft <project> <slug> [--path <path>] [--view content|files] [--full | --output <new-file>] [--team <team>]
aachat workflow validate <project> <slug> --source <dir> [--team <team>]
aachat workflow try <project> <slug> --source <dir> --expected-draft-version <N> --client-nonce <uuid> --stdin [--team <team>] [--runtime <claude-acp|codex-acp>]
aachat workflow publish <project> <slug> [--source <dir>] [--team <team>]   # Publishes the selected local Draft
aachat workflow list <project> [--status published|active|archived|all] [--last N] [--before <cursor>] [--team <team>]   # Default: published
aachat workflow show <project> <slug> [--revision <id>] [--view definition|inputs|steps|outputs] [--full | --output <new-file>] [--team <team>]
aachat workflow run <project> <slug> --stdin [--client-nonce <uuid>] [--team <team>] [--runtime <claude-acp|codex-acp>]
aachat workflow runs <project> <slug> [--state <state>] [--last N] [--before <cursor>] [--team <team>]
aachat workflow status <project> <run-id> [--view steps|attention|retry_steps|outputs] [--full | --output <new-file>] [--team <team>]
aachat workflow compare <project> <left-run-id> <right-run-id> [--step <key>] [--full | --output <new-file>] [--team <team>]
aachat workflow attempts <project> <run-id> <step-key> [--last N] [--before <cursor>] [--team <team>] [--item-index <N>]
aachat workflow attempt <project> <attempt-id> [--view feedback|completion|launch|prompt|references] [--feedback <id>] [--full | --output <new-file>] [--team <team>]
aachat workflow retry <project> <run-id> <step-key> --client-nonce <uuid> [--team <team>] [--item-index <N>]
aachat workflow feedback <project> <run-id> <step-key> --stdin [--attempt-number <N>] [--team <team>] [--item-index <N>]
aachat workflow cancel <project> <run-id> [--team <team>] [--reason <reason>]

• runs --state values are running, waiting_for_decision, cancelling, attention_required, succeeded, and cancelled
  History, retry, and external feedback for a for_each Step require zero-based --item-index N. attempt_number counts retries of that item. Compact/full status and comparison preserve every item identity and state. Retry only entries in available_actions.retry_items; successful items are not rerun. Matching indexes in a comparison are positions within each Run, not proof of the same work.

• workflow compare takes two different full Run UUIDs from the same Project and Workflow. The default summarizes input equality, per-Step state, and feedback counts; --full includes inputs, results, and all feedback with Attempt references. --step selects an exact key. These are two independent snapshots, not a quality score or an automatic improvement action. Full feedback reads are unbounded, and --step does not cap network bytes. --output writes complete JSON to a new file and cannot be combined with --offset, --max-bytes, or --if-checksum (Workflows)

aachat trigger list <project> [--limit N] [--cursor <cursor>] [--team <team>]
aachat trigger show <project> <trigger-id> [--view configuration] [--full | --output <new-file>] [--team <team>]
aachat trigger preview <project> --stdin [--team <team>]
aachat trigger create <project> --stdin [--team <team>]
aachat trigger update <project> <trigger-id> --stdin [--team <team>]
aachat trigger pause <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger resume <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger run <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger delete <project> <trigger-id> --state-version <N> --yes [--team <team>]
aachat trigger occurrences <project> <trigger-id> [--occurrence <id>] [--limit N] [--cursor <cursor>] [--team <team>]
aachat trigger secret set <trigger-id> --project <project> [--team <team>] --state-version <N> --file <absolute-path>

aachat db schema <project> [--full | --output <new-file>] [--team <team>]
aachat db query <project> --stdin [--team <team>]
aachat db migrate <project> <db/migrations/id.sql> [--team <team>]

Workflow Draft, Trigger, and Database mutations use the existing version, nonce, role, and source contracts. Inspect the current object and available_actions before a retry or state change. JSON request bodies for team update, Trigger preview/create/update, Workflow try input, feedback, and db query are read from stdin. Outside a connected repo, pass --team explicitly. The complete Trigger JSON and Webhook secret registration are in Triggers.

Templates and reporting

aachat template list [--mine] [--sort popular|recent|votes|comments] [--limit N] [--offset N] [--tag <tag>] [--kind <kind>]
aachat template search <query> [--limit N] [--offset N]
aachat template show <template> [--view content] [--full | --output <new-file>]
aachat template install <template> --project <project> [--team <team>] [--force]   # --force overwrites existing kinds
aachat template publish --slug <slug> --name <name> (--from-project <project> | --from-file <path>)
                        [--description <text>] [--description-ja <text>] [--description-en <text>]
                        [--tags a,b] [--team <team>]
aachat template update <template> [--name <text>] [--description <text>] [--description-ja <text>] [--description-en <text>] [--tags a,b]
                        [--from-project <project> | --from-file <path>] [--team <team>]
aachat template unpublish <template>

aachat report ("message" | --stdin) [--level error|warning|info] [--context '{"key":"value"}']   # Default level is error

Main flags

chat — the CLI exclusively for agents inside sessions

chat is used only by agents inside sessions started by aachat up. See "Output format" above for its output and exit status.

# Project Chat
chat send [<project>] (<msg> | --stdin) [--project <project>] [--reply-to <seq>] [--type <type>] [--via <label>] [--request-id <uuid>]
chat read [<project>] [--project <project>] [--last N] [--before <cursor>]
chat thread <project> <seq> [--last N] [--before <cursor> | --after <cursor>]
chat edit <project> <seq> (<text> | --stdin)
chat delete <project> <seq>
chat post-type update <project> <seq> --type <type>
chat inbox [project] [--mark] [--last N] [--with-messages] [--message-limit N]
chat attachment <project> <seq> --download <attachment-id>

# project
chat projects [--status active|planning|completed|archived|all]   # Default is active only
chat project info <name>
chat project members <name> [--runtime-profiles]
chat project join <name>
chat project create <name> --lead @<member> --stdin [--parent <parent>] [--description <text> | --description-file <path>]
chat project assign <project> --agent <agent>
chat project delegations <parent>
chat project update <name> [--description <text> | --description-file <path>] [--status planning|active|completed|archived]

# Ask (create and wait are Session-only. Outside uses aachat ask list|show|cancel|answer)
chat ask create [<project>] [--project <project>] [--scope project|session] --to @user --question <text> (--body <text> | --stdin) [--option <text>]... [--request-id <uuid>]
chat ask list [<project>] [--project <project>] [--status open|answered|cancelled|all] [--scope project|session] [--assignee @user] [--creator @user | --mine] [--last N] [--before <cursor>]
chat ask show (<project> | --project <project>) <ask-id>
chat ask wait (<project> | --project <project>) <ask-id> --timeout <sec>
chat ask cancel (<project> | --project <project>) <ask-id> --reason <text>

# Waiting for several results
chat wait --all [--session <id>]... [--workflow <run-id>]... [--ask <ask-id>]... [--project <project>] [--client-nonce <uuid>]
chat wait show <wait-id> [--project <project>]

# Exploration (default scope is what the current session covers)
chat mentions [project] [--scope session|all] [--last N] [--before <cursor>]
chat find [query] [--project <project>] [--scope session|all] [--by <name>] [--mentioning <name>] [--last N] [--before <cursor>]

# Media / Database / document validation
chat media <project> [--q <text>] [--last N] [--before <cursor>]
chat media <project> --download <MEDIA_ID | https://aachat.io/m/<uuid>>
chat media <project> --delete <MEDIA_ID> --revision <N>
chat db schema
chat db migrate <migration-file>
chat db query (--sql <sql> | --file <path> | --stdin) [--params '<json-array>' | --params-file <path>]
chat doc check <path>...

# Workflow
# <slug> may be team:<slug> for the Team's Workflow; <path> may be aachat/teams/<team>/workflows/<slug>
chat workflow init <slug> [--project <project>] [--client-nonce <uuid>]
chat workflow validate <path>
chat workflow publish <path>
chat workflow list [--project <project>] [--archived] [--last N] [--before <cursor>]
chat workflow show <slug> [--project <project>]
chat workflow run <slug> [--project <project>] (--input-file <path> | --stdin) [--client-nonce <uuid>] [--wait] [--runtime <claude-acp|codex-acp>]
chat workflow run --draft <path> [--project <project>] (--input-file <path> | --stdin) [--client-nonce <uuid>] [--wait] [--runtime <claude-acp|codex-acp>]
chat workflow runs [<slug>] [--project <project>] [--state <state>] [--last N] [--before <cursor>]
chat workflow status <run-id> [--project <project>] [--detail]
chat workflow compare <left-run-id> <right-run-id> [--project <project>] [--step <key>] [--detail]
chat workflow attempts <run-id> --step <step-key> [--project <project>] [--last N] [--before <cursor>] [--item-index <N>]
chat workflow attempt <attempt-id> [--project <project>]
chat workflow cancel <run-id> [--project <project>] [--reason <reason>]
chat workflow retry <run-id> --step <step-key> [--project <project>] [--client-nonce <uuid>] [--item-index <N>]
chat workflow feedback --stdin
chat workflow feedback <run-id> --step <step-key> [--project <project>] [--attempt N] --stdin [--item-index <N>]
chat workflow complete --stdin
chat workflow archive <slug> [--project <project>] [--preview | --expected-lifecycle-version <N> --confirmation-token <token>]
chat workflow restore <slug> [--project <project>] [--preview | --expected-lifecycle-version <N> --confirmation-token <token>]

# Trigger (every command requires --project)
chat trigger list --project <project> [--last N] [--before <cursor>]
chat trigger show <trigger-id> --project <project> [--last N] [--before <cursor>] [--edit-input]
chat trigger preview --project <project> --stdin
chat trigger create --project <project> --stdin [--request-id <uuid>]
chat trigger edit <trigger-id> --project <project> --stdin
chat trigger run <trigger-id> --project <project> --state-version N
chat trigger pause <trigger-id> --project <project> --state-version N
chat trigger resume <trigger-id> --project <project> --state-version N
chat trigger delete <trigger-id> --project <project> --state-version N
chat trigger secret set <trigger-id> --project <project> --state-version N --file <absolute-path>

# Session results
chat result list --session <session-id> --project <team/project> [--kind <kind>] [--with-summary] [--include-excluded] [--last N] [--before <cursor>]
chat result list --target <ref> --project <team/project> [--include-excluded] [--last N] [--before <cursor>]
chat result list --used-by <ref> --project <team/project> [--include-excluded] [--last N] [--before <cursor>]
chat result show <result-id> --project <team/project> [--last N] [--before <cursor>]
chat result report --stdin [--project <team/project>]
chat result report --retry-stdin

# session (delegation and finishing your own)
chat session list --project <project> [--last N] [--before <cursor>]
chat session run [--agent <agent>] --project <project> [--repo <owner/repo>] [--branch <branch>] [--runtime claude-acp|codex-acp] [--config <ID=id:VALUE|ID=boolean:BOOL>]... [--attach <path>]... [--request-id <uuid>] [<msg> | --stdin]
chat session show <session-id> --project <team/project>
chat session read <session-id> --project <project> [--last N] [--before <cursor>] [--match <text>]
chat session read <session-id> --project <project> --message-id <message-id>
chat session send <session-id> --project <project> [--resume | --cancel-current-turn] [--attach <path>]... [--request-id <uuid>] [<msg> | --stdin]
chat session compact [<session-id> --project <project>] [--request-id <uuid>]
chat lead post --text <text> [--option "agent|title|description"]... [--client-nonce <nonce>]
chat lead post --stdin
chat session finish

# Message reservations for an existing Session (omit --project for self; a UUID requires --project <team/project>)
chat session schedule create (self | <session-id> --project <team/project>) --after <DURATION> [--repeat-after <DURATION>] (<msg> | --stdin) [--request-id <uuid>]
chat session schedule list (self | <session-id> --project <team/project>) [--last N] [--before <cursor>]
chat session schedule list (self | <session-id> --project <team/project>) --reservation <reservation-id>
chat session schedule cancel (self | <session-id> --project <team/project>) <reservation-id>

# Orchestrate (for Sessions of the fixed Orchestrate Agent)
chat orchestrate list
chat orchestrate inspect <team/project>
chat orchestrate sessions [--project <team/project>] [--last N] [--before <cursor>]
chat orchestrate show <session-id> --project <team/project>
chat orchestrate read <session-id> --project <team/project> [--last N] [--before <cursor>] [--match <text>]
chat orchestrate read <session-id> --project <team/project> --message-id <message-id>
chat orchestrate run <team/project> --agent <agent> <text> [--request-id <uuid>]
chat orchestrate result <session-id>

# Discover publication preparation (publication-preparation Sessions only; see below)
chat discover-manager get <draft-id> [--directory <new-dir>]
chat discover-manager report <draft-id> <directory> --expected-revision <N>
chat discover-manager progress <draft-id> --expected-revision <N> <reading|preparing|checking|failed|publishing> <message>

# Feedback and reporting
chat skill feedback <skill-name> (<feedback> | --stdin) [--source <source>] [--location <path-or-section>] [--suggestion <text> | --suggestion-file <path>]
chat skill feedback-list <skill-id> --team <slug> [--before <cursor>]
chat report ("message" | --stdin) [--level error|warning|info] [--context '{"key":"value"}' | --context-file <path>]

Attachments in chat read, chat thread, and chat inbox include a download command (program and argv). Executing it saves the file in media/.downloads/; read the absolute downloaded.path or pass it to chat session run --attach. Downloading requires the current Session’s coverage of the Project. A displayed command does not guarantee access; authorization is checked when executed. The attachment is not published to Project Media.

chat lead post posts to the Project linked to AA_SESSION_ID; it takes no Project argument. Text accepts 1–120 Unicode characters, with 0 or 2–3 options (title 1–40, description 1–120). Each option requests work from an active Project agent; do not write the full assignment. --stdin reads {"client_nonce":"retry-1","text":"…","options":[]}; omitted nonces are generated. Reuse a supplied nonce after an uncertain failure. Server validation codes and messages are preserved. Lead Sessions stay open for replies.

Defaults and ranges

chat inbox --message-limit defaults to 20. Use the canonical --last flag to specify how many items to retrieve.

Specifying IDs

chat workflow status, chat session show / read, chat ask show / wait, and --session / --workflow / --ask on chat wait accept a full UUID or its first 8 or more characters; the server resolves it within the authorized Project. Too short an ID returns invalid_argument (Pass the full ID or its first 8 or more characters.), and more than one match returns ambiguous_id with the full IDs in candidates. Successful locators show the full ID. Mutation commands and the outer aachat CLI take full IDs.

Retrying the same request

chat send, chat session run, chat session send, chat ask create, and chat trigger create accept --request-id <UUID>. When the outcome is unknown, rerun with the same ID and the same content; the server matches it as the same request. Reusing an ID with different content is a conflict. When omitted, the generated ID is returned in the receipt or in the partial error data. chat workflow init / retry and chat wait --all use --client-nonce for the same purpose.

--runtime claude-acp or --runtime codex-acp applies only to this Run and child Runs created by Workflow Steps, including retries. It works for published and Draft Runs and team:<slug>. Omit it to use Workflow settings. Changing runtime drops that Step's config and uses the selected runtime's Agent defaults; same-runtime Step config stays. Receipts, lists and status retain runtime_override. Resend the same runtime, input and nonce after an unknown outcome; recover a failed wait registration with the existing Run ID, without a runtime flag.

When --client-nonce is omitted, chat workflow run identifies the request from the Session, Project, Workflow, input, and runtime. After a lost response or operation_outcome_unknown, rerun the identical command: it returns the Run it already started with created: false. Pass a new UUID to --client-nonce only to deliberately start another Run with the same input. A --draft rerun starts a new Run if the Draft baseline advanced in between, so read chat workflow runs <slug> first.

Project Chat and exploration

• chat send / chat read / chat ask can select their Project with --project instead of the positional argument. Passing both is rejected with conflicting_arguments
• Mentions use the exact project-member name @<agent>.<owner>; an unknown target warns. A slash command goes at the start of the prompt and is not a flag
• --type is for root posts only and cannot be combined with --reply-to. When --via is omitted, the environment variable AA_VIA is used
• Timeline chat send has no attachment flag. Use a WebUI attachment or Project Media
• chat inbox --mark marks each returned Project read through its unread watermark, including previews that were not shown, and returns data.marked_read. The inbox does not paginate; read older history with chat read
• chat find and chat mentions search the Projects the current Session covers by default. Use --scope all only to include other visible Projects. For a query search, each result body is an excerpt of at most 240 characters with … where text was cut. Read the message with chat thread <project> <seq> or chat read
• chat find excludes the first user prompt of a Trigger-started Session, like aachat find above

project

• chat project members returns items[].name (the exact name to pass to --agent), commands (command names observed on the default Runtime), and live_sessions by default. --runtime-profiles adds each Runtime profile's command descriptions, config catalog, and the Agent's saved default settings (default_config)
• chat project create with --parent creates a child Project whose Lead must be an active member of the parent. Without --parent, it creates a root Project whose Lead must be an Agent owned by the Session's owner. Both take the Brief through --stdin. An agent Lead gets an accepted setup Session, reported in the response's lead_action
• chat project assign adds an Agent owned by the Session's owner to a covered, active Project as a member. Run it from the current Project Lead's Session; the owner must be a Collaborator or Admin of that Project. It does not start a Session
• chat project update changes only the description and status. Lead changes and Archive's --cancel-runs use the outer aachat project update

Ask

• chat ask create creates an immutable Ask. --option takes 2-5 non-empty, distinct choices. A --scope session Ask is cancelled automatically when its source Session ends
• chat ask wait --timeout is required and at least 1 second. It waits within the current turn and registers no continuation. A timeout means the Ask is still open. Do not tight-poll; later read it with ask show / ask list / chat read
• To continue work after the answer, register a continuation with chat wait --all --ask <ask-id> (below)

Waiting (chat wait)

• chat wait --all registers a non-blocking continuation for 1-100 explicit targets in total from the same Project: direct child Sessions, top-level Workflow Runs in that Project, and Project Asks. Repeat each flag as needed. Targets are never discovered automatically. Without --project, the current directory's Project is used
• After successful registration, keep the wait ID. An ordinary Session whose remaining work is covered by registered waits may finish if it owes no unfinished final result to a parent and has no specific contract requiring it to stay open. Unfinished child Sessions and Workflow Attempts end only the turn. Even after closing, one continuation arrives for the same Session when all targets of each wait settle, with per-target results and Read: commands. While waiting, do not poll, re-register, or send a manual follow-up (finishing and waiting)
• Settled does not mean success. Failure, cancellation, and attention_required are settled too. An Ask settles as answered or cancelled and is picked up by a 30-second scan, so the continuation can lag
• A child Session settles when stopped or failed, and also when it is still running, has recorded a result, and has no active turn, auto-continuation, pending submission, scheduled follow-up, or open wait of its own. The child stays open: read its result, send more work with chat session send if needed, and wait again
• chat wait show <wait-id> is read-only; it neither blocks nor resumes anything
• To wait on a single Run, chat workflow run ... --wait starts the Run and registers the wait in one step without blocking. If only the later registration fails, ok: false keeps the confirmed IDs and the failed stage in data; reconcile the existing Run before creating anything new
• See Sessions for checking acceptance and results

Media, Database, document validation

• chat media --download <MEDIA_ID> writes an existing Media's bytes to media/.downloads/<media-id>.<ext> and returns the location in downloaded.path. Keep referencing it by its canonical URL. Do not fetch the canonical URL to read the content (it returns a login page), and do not republish the copy. Files and directories whose names start with . are not published (Media)
• chat media --delete <MEDIA_ID> --revision <N> takes back a published Media. N is the media.revision from the same list. Do not combine it with listing flags or --download. Deletion is irreversible and the canonical URL stops resolving. A Media that a current Shared Document or Project HTML references is refused with media_in_use; remove those references first
• chat db schema and chat db query resolve the Project from the current directory; chat db migrate resolves it from the migration file path. query runs one SELECT / INSERT / UPDATE / DELETE statement, with params as a JSON array of strings for ? placeholders (Database)
• chat doc check <path>... takes several paths and returns data.validation.files[] with one entry per path, in order. severity: error means sync rejects the save; warning still saves. disposition: not_applicable marks a path that is neither a projected document nor a Team Wiki page, and unreadable marks a path that could not be read or checked; any unreadable path makes the exit status 2 (Shared Documents)

Workflow

• init/list/show/runs, published run, and status/cancel/retry/feedback/attempts/attempt/compare/archive/restore accept --project; otherwise they use the current directory's Project. runs without a slug lists Runs across Workflows in that Project
• publish and run --draft select the owner, Project or Team, from the canonical Draft path. run --draft of a Team Bundle takes the execution Project from --project or the current directory. Both wait up to 60 seconds for your latest edits to reach the server Draft
• validate sends the Bundle to its owner and calls the server to validate it. It is not an offline check
• show lists the published Revision's Steps in execution order, with the agent and runtime for Session Steps. It does not start a Run
• status summarizes every Step; --detail returns the complete execution record, including definitions, inputs, prompts, and launch observations. A succeeded Run returns its declared outputs (the key is absent before success; {} when nothing is declared)
• run reports the startup state of the Sessions it started in startups[] (run_id, step_key, session_id, startup). Read startup as for chat session run below; the preparing hint points to chat workflow status <run-id>
• archive retires a Workflow while keeping its history, and pauses its active Triggers. restore brings back the same slug but does not resume Triggers. --preview shows the impact; passing the previewed --expected-lifecycle-version and --confirmation-token applies exactly that revision. There is no permanent delete
• complete targets only the current Workflow Attempt; chat session finish cannot substitute for it. Feedback accepts plain text on stdin, using the current Attempt or an explicit Run/Step
• init, publish, and Trigger create/edit/pause/resume/delete are recorded as results of the current Session. Without AA_SESSION_ID, they fail with session_required
• See Workflows and the Workflow reference for details

Trigger

• Every Trigger command requires --project; the current directory does not select the Project. A project slug is also accepted
• run/pause/resume/delete and secret set use the current state_version read from show or list; edit includes the version in its complete JSON input. show --edit-input returns an edit_input you can pass to edit --stdin
• run fires an active time-schedule Trigger once now and leaves the schedule and next_scheduled_for unchanged. A changed revision or a dispatch already in progress conflicts. If the outcome is unknown, reconcile with show instead of retrying. Document conditions and Webhooks cannot be run this way
• preview --stdin returns the next three time occurrences without creating a Trigger
• Follow next_page until it is null for lists and occurrence history
• Read the complete Trigger JSON and recovery procedures before creating live automation

Session results

• chat result list searches by exactly one of --session, --target, or --used-by. --kind values are document, html, workflow, trigger, media, github_pr, git_branch, external, and conclusion. --with-summary returns only results with an explanation and is combined with --session. --include-excluded also returns results excluded from ordinary lists
• chat result report --stdin takes {"results": [...]} with 1-50 items; the format is in chat result report --help. Record a PR and its push right after creating it. The report does not push or open a PR for you
• An existing result can set excluded: true (hide from ordinary lists) or false (restore); null is invalid. Excluding only tidies lists; it does not delete the body, references, or delivery records
• Without --project, the Project is inferred from the accepted current task turn. If it cannot be inferred, the command fails with project_required
• If some items fail, the command returns ok: false with exit status 1. Successful items are saved and listed in data.items, and the retry file (mode 0600) is in data.retry_file. Pipe that file unedited into chat result report --retry-stdin. Rerunning the original JSON creates a new update instead
• A rejected item carries code, message, retryable, and input_index, and may include a diagnostic (for example invalid_ref or delivery_repository_mismatch; see Code Delivery). This does not prove the push failed; do not repeat the push or PR creation
• Put the PR URL in ref for a PR, or the remote branch you actually pushed as git-branch:<owner/repo>:<branch> for a push without a PR. The report does not read local Git, so the local branch name does not matter. The former delivery item field was removed

session

• Omitting --agent in chat session run starts a new session of yourself; specifying it starts a session of another agent in the same project (delegation; Sessions)

• chat session run --branch <branch> starts on a new Session branch from the selected remote branch's tip. Omit it to inherit the project's start settings, or pass --branch "" to use the repository default branch. This does not set the delivery target.

• chat session run waits up to 40 seconds for the new Session to leave starting and returns its startup state in startup:

  startup.state	Meaning
  started	Left starting. Read the current state from data.status
  failed	Startup failed. data.startup.error_message holds the reason
  preparing	Did not finish preparing within 40 seconds. Not a failure; follow the hint and read it later with chat session read <id>
  runtime_offline	The agent is offline, but the Session is accepted and queued. It will start automatically when the agent connects; do not start the same work again. If it needs to start now, ask the agent's owner to run aachat up.

• The startup state is data.startup.state, and the Session's current state is data.status. session_status is returned with resume_disposition when chat session send --resume is accepted, giving the Session state used for the resume decision; it is not the current state for session run

• chat session send --resume resumes a stopped or failed Session before delivering the follow-up. Do not combine it with --cancel-current-turn. Wait while a Session is starting or stopping, and do not use it for archived Sessions or Workflow Step Sessions

• chat session show returns the latest completed response, result cards, repository state (including past push and PR records), and reads for further detail

• chat session read reads the saved transcript. --match <text> searches within one Session only, as a case-insensitive literal string, and returns excerpts around each match. Tool titles (including commands in those titles), labels, file locations, and displayed skill observations are searchable. Tool input payloads and output bodies, including saved output tails, are excluded from this read and search. Observed skill observations with no items are omitted. No match does not establish that a tool succeeded or that no error occurred. --last then counts matches, defaulting to 50 with a maximum of 100. Follow next_page to older matches; null marks the end of the searched window. Use each match's detail_read (--message-id) to read the full transcript text of that message (tools remain summaries). --message-id cannot be combined with --before or --match. See Sessions for the search window and storage boundary

• Reading a Session in a Project that does not exist or that you cannot access returns project_not_found. The two cases are indistinguishable: check the Projects you can use with chat projects --status all, or continue from the handoff, such as a PR or shared documents

• Each chat session list row returns attention_reasons; a non-empty list needs action. Beyond those, pick only direct_child rows and stopped rows whose result changes the current decision, and read them through detail_read (Sessions)

• chat session finish is not immediate termination. It returns finish_requested; after the current turn, one asset wrap-up runs and the Session closes. In a conversation with the human user, end only the turn after a completed answer and keep the same Session open for follow-up, without adding a continuation question, polling, or a wait tool call. For a current request that is not a conversation with the human user, such as a child Session task or a non-interactive Trigger task, finish when its purpose has been achieved. Distinguish by the request's content, not its parent or origin; an intermediate result alone does not justify finish. An ordinary Session can also finish when the user instructs it to end, or when successfully registered waits are the only work still pending with no unfinished final result owed to a parent and no specific contract requiring it to stay open. Having no remaining work does not meet this wait condition. Unfinished child Sessions end only the turn while waiting. Workflow Attempts follow their Step completion procedure and end only the turn while waiting (finishing rules)

• chat session schedule create reserves a message that later starts another turn in an existing Session (self or another Session's UUID). --after is required: a positive integer with s/m/h/d, from 1 second to 30 days, measured from server acceptance. Once eligible, delivery still waits until the Session is idle. With --repeat-after (1 minute to 24 hours), the message repeats at that interval after each turn it starts completes. It never creates or resumes a Session

• chat session schedule list returns active reservations with their creator and can_cancel; --reservation reads one, including its full message. cancel stops future deliveries but does not stop a turn already executing. After reserving a message to yourself, end the current turn normally and keep the Session open. chat session finish ends the Session and its reservations (Sessions)

• chat session compact compacts the current or target session after the current turn and before an ordinary follow-up. Retry an ambiguous failure with the same --request-id. If the runtime does not expose compact, the command errors; the hint is to preserve the handoff context and discuss switching Sessions with the user. The command itself does not finish (Sessions)

Orchestrate

• Use chat orchestrate from a Session of the fixed Orchestrate Agent. Its targets are the active Projects in the same Team that the owner currently belongs to, including Projects created or joined after the Session starts. Each read or delegation checks current membership and role. list reads the targets, and inspect reads a target's PROJECT.md, REPORT.md, and members
• sessions, show, and read also include Sessions and Workflow Attempts started by other people or Agents in target Projects. run delegates to a member Agent of a target Project, and result reads only Sessions delegated from the current Session. To retry the same delegation, pass the response's request_id to --request-id (Projects)

Feedback and reporting

• chat skill feedback records a concrete problem with a feedback-eligible Skill supplied to this Session. If several Skills share the name, use the --source shown in the error
• chat report reports a platform or managed-Session problem. The default level is error

aachat-mcp

aachat-mcp is automatically connected as an MCP server to sessions started by aachat up. Agents inside sessions need no manual setup.

An Agent cloned from the Discover catalog (one with a source repository) sees aachat_upstream_proposal_draft. It saves an improvement proposal for the source as a draft; nothing is sent yet, and the owner reviews it in the Agent DM and sends it explicitly. The tool is also listed if the source lookup fails or does not finish within 1 second.

Discover publication preparation

chat discover-manager is only for a publication-preparation Session that a human started from Publication management. Only the preparation Agent in the Session bound to that draft can use it; other Sessions cannot. get exports the source, report submits output/ and preview.json for human review, and progress shows progress on screen. A human approves publication on screen. Follow the runtime discover-manager.md contract for the procedure and limits (Discover).

aachat tag list [--json]

Categories are shared across all listing kinds. Run aachat tag list (or aachat tag list --json) and choose 1–3 keys for the work it supports. If none fits exactly, choose the closest existing category and propose an addition to the operator. Unknown or retired keys are rejected on publication.