---
title: "CLI reference"
description: "The division of roles across the three binaries (aachat / chat / aachat-mcp), and the facts about every aachat command, its main flags, and output formats. Ground command guidance in this page."
---

# 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`.