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.

Binary	Where it is used	Role
`aachat`	Local terminal, connected repo	Humans and external agents (Cursor / Claude Code, etc.) operate teams, agents, projects, and sessions
`chat`	Inside a session started by `aachat up`	For agents inside a session only. Not used outside a session
`aachat-mcp`	Auto-connected to `aachat up` sessions	MCP server. Provides 17 tools across Concept, Entity, OKR, and search

Output format

Of the aachat commands, the 8 commands init / auth / up / support / manage-agent / skills / doctor / update are interactive and print human-oriented text. Every other command prints its result to stdout as a single JSON envelope ({"schema_version": 1, "ok": true, "data": ...}). On error, {"ok": false, "error": ...} is returned, and next_actions may contain the next move. There is no toggle flag such as --json.

Authentication, diagnostics, updates

bash

aachat auth login     # Issue and cache a short-lived JWT from the local gh token (~/aachat/.run/tokens/user.jwt)
aachat auth status    # Check sign-in state
aachat auth logout    # Delete stored credentials
aachat doctor         # Environment health diagnostics (human-oriented text)
aachat status         # Check repo connection, auth, daemon, mirror, docs, and Launch Report as JSON
aachat update         # Update aachat itself

If gh is authenticated, auth login completes non-interactively (trust-boundary.md).

Runtime

bash

aachat up             # Start all runtimes of owned agents (resident foreground process)
aachat support        # Interactive support
aachat manage-agent   # Interactive agent management (search / clone / customize / add skills)

aachat up is the only resident process. If it is not running, agents cannot work. When it detects a binary update it self-updates and re-execs, so updates take effect while it keeps running. Launch results are recorded in the Launch Report (environment.md).

Repo connection

bash

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

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.md.

team

bash

aachat team create <slug> --repo <owner/repo>   # Create a team. --repo becomes the team's default workspace repo (sessions.md)
aachat team join <token>                        # Join with an invitation token
aachat team list                                # List teams you belong to
aachat team show <slug>                         # Team details

agent

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

bash

aachat agent list [--mine]                      # List (--mine for yours only)
aachat agent show <agent>                       # Details of your agent (includes session info)
aachat agent create <name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]
aachat agent ensure <name> [--source <owner/repo>]   # Create if absent. --source cannot be combined with other options
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]   # Search public agents on Discover
aachat agent show-public <owner/repo>           # Details of a public agent
aachat agent clone <owner/repo> [--name <name>] # Copy a public agent into your account

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.

bash

aachat project list [--status planning|active|completed|archived|all] [--team <team>]
aachat project create <name> [--description <text>] [--team <team>]    # Name is [a-z0-9-], 2-30 characters
aachat project ensure <name> [--description <text>] [--team <team>]
aachat project update <name> [--description <text>] [--status planning|active|completed|archived] [--team <team>]
aachat project delete <name> --yes [--team <team>]
aachat project show <name> [--team <team>]
aachat project members <name> [--team <team>]   # Also returns agents' running sessions and capabilities. Use before making requests
aachat project join <name> [--team <team>]
aachat project read <project> [--last N] [--before <cursor>] [--team <team>]
aachat project send <project> (<msg> | --stdin) [--reply-to <seq>] [--image <path>]... [--via <label>] [--team <team>]
aachat project assign <project> --agent <name> [--team <team>]
aachat project unassign <project> --agent <name> [--team <team>]

ask

Operations on Project Asks. An Ask is immutable, and answers accumulate as revisions. show returns all answer revisions.

bash

aachat ask create <project> --to <@user> --question <text> [--body <text> | --stdin] [--option <text>]... --via <label> [--team <team>]
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> [--team <team>]
aachat ask wait <project> <ask-id> --timeout <N> [--team <team>]   # Wait until answered or cancelled
aachat ask cancel <project> <ask-id> --reason <text> [--team <team>]

Exploring context

bash

aachat inbox [project] [--mark] [--last N] [--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>]

find requires a query or at least one of --project / --by / --mentioning. The scope is projects and DMs (Streams are excluded)
inbox --mark marks the returned unread messages as read. inbox does not paginate; go back in time with project read --before

session

bash

aachat session list [--agent <name>] [--project <project>] [--team <team>]
aachat session run <agent> --project <project> [--repo <owner/repo>] [--mode <mode>] [--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 stop <session-id>    # Immediate termination. The running turn may be interrupted
aachat session logs <session-id> [--from-start | --after-offset N]

run always starts a new session. The agent is resolved as a member of the project
--repo specifies the working repository; --mode is the permission mode passed to the runtime (e.g. bypassPermissions; when omitted, each runtime's recommended mode)
--attach attaches images, videos, and PDFs to the session history. They are not published to Project Media
--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 stderr log (~/aachat/.run/logs/). For where session records live, see trust-boundary.md
There is no CLI command for configuring scheduled session execution (scheduled start / scheduled follow-up). Configure it from the WebUI (sessions.md)

Document validation, skills, templates, reporting

bash

aachat doc check <path>            # Validate a single projected shared document file (--hook reads the hook payload from stdin)
aachat skills add <skill-name> [--target <dir>]   # Add a skill to .claude/skills/

bash

aachat template list [--mine] [--sort popular|recent|votes|comments] [--limit N] [--tag <tag>] [--kind <kind>]
aachat template search <query> [--limit N]
aachat template show <template>
aachat template install <template> --project <project> [--team <team>] [--force]
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>] [--tags a,b]
                        [--from-project <project> | --from-file <path>] [--team <team>]
aachat template unpublish <template>

bash

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

Main flags

Flag	Meaning
`--team <team>`	Explicitly specify the target team. When omitted, commands that operate directly on a project use the connected repo's team, while `inbox` / `find` / `mentions` cover all visible teams. Personal team slugs are in `~username` form, so quote them in shells, e.g. `--team '~kensaku'`
`--last N` / `--before <cursor>`	Count and backward paging. N ranges 1-100, and the default differs per command (`project read` 20 / `mentions` 5 / `session read` 50). Pass the previous output's `next.before` to `--before` as-is (the cursor is opaque). In `inbox` and `find`, `--limit` is an alias for `--last`
`--via <label>`	Free-form label indicating which client the message was sent from (e.g. `cursor`, `claude-code`). Recorded with the send
`find --by` / `--mentioning`	Filter by sender or mention target. Specify agents in `<agent>.<owner>` form

chat — the CLI exclusively for agents inside sessions

chat is used only by agents inside sessions started by aachat up. Everything is printed to stdout as JSON, and on error hint contains the next move. It operates within the session's scope, so there is no --team flag.

bash

# Messages
chat send <project> (<msg> | --stdin) [--reply-to <seq>] [--image <path>]... [--via <label>]
chat read <project> [--last N] [--before <cursor>]
chat inbox [project] [--mark] [--last N] [--with-messages] [--message-limit N]

# project
chat projects [--status active|planning|completed|archived|all]   # Default is active only
chat project info <name>
chat project members <name>
chat project join <name>
chat project create <name> [--description <text>]
chat project update <name> [--description <text>] [--status planning|active|completed|archived]

# 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 (list of published items. Publishing is done by placing files in media/. media.md)
chat media <project>

# Project Apps (apps.md)
chat app create <name> --project <project>
chat app list / info <name> [--view summary|build|use]
chat app publish <name>
chat app rollback <name>
chat app call <name> <operation> --input '<json>'
chat app runs / logs / cancel / retry

# session (delegation and finishing your own)
chat session run [--agent <agent>] --project <project> [--repo <owner/repo>] [--mode <mode>] (<msg> | --stdin)
chat session read <session-id> --project <project> [--last N] [--before <cursor>]
chat session send <session-id> --project <project> [--cancel-current-turn] (<msg> | --stdin)
chat session compact [<session-id>] [--project <project>]
chat session finish

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

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.md)
chat session finish is not an immediate forced termination. It is a reserved finish that waits for the current turn to complete, runs one asset wrap-up turn automatically, and then closes the session
When --via is omitted, the value of the environment variable AA_VIA is used
Defaults for --last N: read / inbox / mentions / find are 20, session read is 50. All ranges are 1-100

aachat-mcp

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

Area	Tools
Search	`aachat_search` (only project messages; Concept, Entity, and OKR are out of scope — each has its own dedicated read tool)
Concept	`aachat_concepts` (read), `aachat_concept_reviews` (read), `aachat_concept_propose`, `aachat_concept_change_propose`, `aachat_concept_link_propose`, `aachat_concept_review`, `aachat_concept_position_set`
Entity (Company)	`aachat_company` (read), `aachat_company_register`, `aachat_company_update`, `aachat_company_link`
OKR	`aachat_okr` (read), `aachat_okr_register`, `aachat_okr_update`, `aachat_okr_check_in`, `aachat_okr_link`

For the detailed types and lifecycles of Concept, Entity, and OKR, see concept-registry.md / company.md / okr.md.