Operate

CLI reference

Every costaff subcommand in one place. Lifecycle, agent and channel management, database, doctor, and direct interaction.

Global

Command	What it does
`costaff --help`	Show the top-level command list.
`costaff <command> --help`	Show options and arguments for a specific command.
`costaff --install-completion`	Install shell completion for your shell.

First-time setup

Command	What it does
`costaff onboard`	Interactive wizard — writes `~/.costaff/costaff/.env` with model provider, language, timezone, and any channels you pick. See First-run setup.
`costaff bootstrap -k <gemini-key>`	Non-interactive one-shot deploy for CI / automation. Writes minimum env (Gemini key, model, language) then chains into `costaff start`. Falls back to `$GOOGLE_API_KEY` if `-k` is omitted.

Lifecycle

Bring the stack up, take it down, watch logs.

Command	What it does
`costaff start`	Preflight-validates `.env` (model key, DB URI, secrets — fatal issues abort with the exact fix), then layered start: Postgres → registered agents → Manager → channels. Builds images if missing.
`costaff start --no-build`	Same, but skip image build (fast restart).
`costaff start --no-preflight`	Skip the `.env` preflight validation.
`costaff stop`	Stop all containers; volumes retained.
`costaff restart`	Equivalent to `stop` + `start`.
`costaff core-rebuild`	Rebuild the Manager + core MCP server image and force-recreate them, then reconnect every plugin agent (whose MCP session to the core would otherwise be stale).
`costaff status`	Show all services' container status.
`costaff logs [service]`	Tail logs (last 100 lines). With no argument, shows all services.

Agent management

Add, remove, restart, and tune specialist agents. See Specialist agents for the full workflow.

Command	What it does
`costaff agent add <name> --github <url>`	Clone a public GitHub repo, validate the manifest, build + start the agent.
`costaff agent add <name> --local <path>`	Deploy an agent from a local directory (no clone).
`costaff agent add <name> --url <a2a-url>`	Register a remote A2A endpoint — no local container.
`costaff agent add ... -e KEY=VAL`	Pre-supply env vars (skips the interactive prompt).
`costaff agent add ... --strict`	Reject the manifest if it doesn't pass the full Agent Protocol JSON Schema (otherwise warns).
`costaff agent add ... --enable-transfer [-y]`	Wire this agent via `sub_agents` + `transfer_to_agent` instead of the default `AgentTool`. Flips the Manager into transfer mode globally — needs confirmation unless `-y`.
`costaff agent list`	List every registered agent with its A2A URL, a health check, and (if pinned) the `Ref` column.
`costaff agent restart <name>`	Restart the agent's container; no rebuild — fast.
`costaff agent rebuild <name>`	Rebuild the image and restart. Needed after code or env-var changes. If the agent was added with `--tag`, sticks to that ref via `git fetch --tags && git checkout <ref>`; otherwise `git pull --ff-only`.
`costaff agent add ... --tag <ref>`	Pin to a git tag, branch, or SHA at install time. Clones with `--branch <ref>` + full history; ref persisted to `config.json`.
`costaff agent rebuild ... --tag <ref>`	Bump (or set) the pin. Persists the new ref to `config.json`.
`costaff agent rebuild ... --no-pull`	Skip git entirely — build from the current working tree (useful when you've hand-edited `~/.costaff/costaff-agent/<name>/src/`).
`costaff agent remove <name>`	Stop, remove, and unregister.
`costaff agent enable <name>` / `disable <name>`	Toggle whether the Manager dispatches to the agent (without removing it).
`costaff agent model <name>`	Query or set the LLM model for one agent.
`costaff agent transfer <name> --enable` / `--disable`	Switch an existing agent between AgentTool (default) and transfer mode.
`costaff agent tags <name>`	List release tags available in the agent's repo (candidates for `--tag`).

restart vs rebuild

restart uses the existing image and is the right call for clearing a stuck container. rebuild is needed whenever you've changed agent source code or its .env — otherwise the new code or env vars won't take effect.

Channel management

Add and manage the front-door chat surfaces. See Chat channels for the full workflow.

Command	What it does
`costaff channel add <name>`	For an official channel name (`webchat`, `telegram`, `discord`, `line`), auto-resolves to the GitHub repo.
`costaff channel add <name> --github <url>`	Clone a custom channel repo and deploy.
`costaff channel add <name> --local <path>`	Deploy a channel from a local directory.
`costaff channel add ... -e KEY=VAL`	Pre-supply env vars (e.g. `TELEGRAM_BOT_TOKEN`).
`costaff channel list`	List registered channels with port, health, and (if pinned) the `Ref` column.
`costaff channel rebuild <name>`	Rebuild image and restart. If the channel was added with `--tag`, sticks to that ref; otherwise `git pull --ff-only`.
`costaff channel add ... --tag <ref>`	Pin to a git tag, branch, or SHA at install time.
`costaff channel rebuild ... --tag <ref>`	Bump (or set) the pin.
`costaff channel rebuild ... --no-pull`	Skip git entirely; build from current working tree.
`costaff channel remove <name>`	Stop, remove, unregister.
`costaff channel tags <name>`	List release tags available in the channel's repo (candidates for `--tag`).

Database

The bundled Postgres holds sessions, project tasks, and identity tables.

Command	What it does
`costaff database info`	Show connection info and table summary.
`costaff database backup [output]`	Dump to a file (default path used if no argument).
`costaff database restore <file>`	Restore from a backup file.
`costaff database clean`	Truncate all CoStaff tables — destructive, asks first.

Doctor & maintenance

Command	What it does
`costaff doctor`	One-shot diagnostic — checks env vars, Docker, container health, network, and the database, then ends with a Suggested fixes list and saves a timestamped report. The first thing to run (and attach) when asking for help.
`costaff update`	Pull latest `costaff` repo and reinstall the CLI.
`costaff update --tag <ref>`	Pin the core repo itself to a specific tag, branch, or SHA, then reinstall.
`costaff license`	Show the installed license and feature gates.
`costaff config validate`	Lint `~/.costaff/costaff/config.json` against the expected schema.

Direct interaction

Useful for scripting and inspecting the Manager without going through a channel.

Command	What it does
`costaff dashboard [--port 8501]`	Launch the host-side FastAPI dashboard (separate from the agent containers).
`costaff chat [app_name]`	Interactive REPL with the Manager (default `costaff_agent`).
`costaff invoke "<prompt>"`	Send a single prompt to the Manager and print the response.

Version pinning

Agents, channels, and the core itself can all be pinned to a specific git tag, branch, or SHA. Once pinned, rebuild stays on that ref instead of pulling the latest main.

# Install pinned to a specific tag
costaff agent add ba --github https://github.com/costaff-ai/costaff-agent-business-analysis \
  --tag v0.1.0

costaff channel add telegram --tag v0.1.0
costaff update --tag v0.1.0   # pin the core too

# Subsequent rebuilds stay on the pinned ref
costaff agent rebuild ba

# Bump the pin to a new version
costaff agent rebuild ba --tag v0.2.0

# Skip git entirely — build from the working tree as-is
costaff agent rebuild ba --no-pull

# See what's pinned
costaff agent list      # Ref column shows the active ref
costaff channel list

Don't manually git pull on a pinned repo

If an agent is ref-pinned, git pull in ~/.costaff/costaff-agent/<name>/src/ will detach HEAD and drift from what the next rebuild expects. Use rebuild --tag to change versions.

Entries written before tag pinning shipped have no ref field in config.json and continue to follow the default branch via git pull --ff-only.

Where the CLI lives on disk

Path	What it is
`~/.costaff/.venv/bin/costaff`	The installed CLI entry point.
`~/.costaff/costaff/`	The git checkout the CLI runs from. `git pull` + `pip install -e .` is what `costaff update` does.
`~/.costaff/costaff/.env`	Core env: model provider, secrets, DB URI. Edited by `onboard`.
`~/.costaff/costaff/config.json`	Registered agents and channels. Edited by `agent add` / `channel add`.
`~/.costaff/costaff-agent/<name>/`	Per-agent source and `.env`.
`~/.costaff/costaff-channel/<name>/`	Per-channel source and `.env`.
`~/.costaff/workspace/`	Shared workspace bind-mounted into every container as `/app/data`.

Uninstall completely

# stop everything
costaff stop

# remove containers, images, and the docker network
docker compose -f ~/.costaff/costaff/docker-compose.yaml down --rmi local --volumes

# (optional) wipe the Postgres data volume
docker volume rm costaff_postgres_data

# (optional) delete the install directory and all your data
rm -rf ~/.costaff

Also remove the # CoStaff Agent CLI PATH line from ~/.zshrc / ~/.bashrc if you want a fully clean shell. After this you're back to the state before installing.