CLI

The gaia command-line interface. Run gaia --help or gaia <group> --help for the live version of any of these.

`gaia acl`

Inspect and manage ACL capabilities.

`gaia acl grant`

Grant a user a capability.

gaia acl grant <ref> <capability>

`gaia acl list`

List the capability groups and the tools each grants.

gaia acl list

`gaia acl perms`

Show a user’s effective capabilities (role defaults + grants, minus denies).

gaia acl perms <ref>

`gaia acl revoke`

Revoke a capability from a user.

gaia acl revoke <ref> <capability>

`gaia chat`

Chat with Gaia in the local terminal.

gaia chat

`gaia config`

Inspect and edit gaia.yaml.

`gaia config edit`

Open gaia.yaml in $EDITOR; warn if the result doesn’t parse.

gaia config edit

`gaia config get`

Print one config value (the effective value, including schema defaults).

gaia config get <key>

`gaia config path`

Print the path to the active gaia.yaml.

gaia config path

`gaia config set`

Set a config value in gaia.yaml (comment-preserving).

gaia config set <key> <value>

`gaia connect`

Set up chat connectors: pick them from a menu, then connect each one.

gaia connect <connectors> [options]

Option	Description
`--token`	Telegram bot token (skips the prompt).
`--verify`	Check the telegram token via getMe.
`--timeout`	Seconds to wait for the WhatsApp QR scan.

`gaia cron`

Schedule jobs gaia runs on its own.

`gaia cron disable`

Disable a job without deleting it.

gaia cron disable <job_id>

`gaia cron edit`

Open the whole job file in $EDITOR (crontab -e style); validates on save.

gaia cron edit

`gaia cron enable`

Enable a disabled job.

gaia cron enable <job_id>

`gaia cron list`

List every scheduled job.

gaia cron list

`gaia cron new`

Add a job: EXPR MESSAGE, or –every N / –at WHEN with MESSAGE.

gaia cron new <expr> <message> [options]

Option	Description
`--every`	Interval in seconds (min 30).
`--at`	One-shot ISO datetime (auto-deletes).
`--name`	Short label.
`--channel`	Deliver to this connector (telegram/whatsapp).
`--chat`	Chat id on that connector.

`gaia cron rm`

Delete a job.

gaia cron rm <job_id>

`gaia cron show`

Print one job in full (raw JSON with –json).

gaia cron show <job_id>

`gaia dev`

Launch ADK’s dev web UI on Gaia — inspect tool calls and LLM requests live.

gaia dev [options]

Option	Description
`--host`	Dev web UI host.
`--port`	Dev web UI port.

`gaia doctor`

Run offline health checks and report OK/WARN/FAIL per item (exit 4 on any FAIL).

gaia doctor

`gaia grow`

Run and review gaia’s self-improvement.

`gaia grow list`

List the skill/soul changes in git history (newest first).

gaia grow list

`gaia grow revert`

Revert one change by commit sha (a new commit undoing it).

gaia grow revert <commit>

`gaia grow run`

Run one self-improve cycle now. Default applies autonomously; --dry-run previews;

gaia grow run [options]

Option	Description
`--dry-run`	Analyze and print proposals without applying.
`-i`, `--interactive`	Approve each proposal before applying.

`gaia grow show`

Show a change’s full commit message + diff.

gaia grow show <commit>

`gaia logs`

Tail (and optionally follow) one of Gaia’s log files.

gaia logs [options]

Option	Description
`-f`, `--follow`	Follow the file (survives rotation).
`-n`, `--lines`	How many trailing lines to print.
`--errors`	Show errors.log (WARNING+).
`--events`	Show events.jsonl (structured activity).
`--daemon`	Show daemon.log (start/serve).
`--json`	With –events: print raw JSON lines, not pretty.

`gaia memory`

Inspect and clear long-term memory.

`gaia memory forget`

Wipe a user’s long-term memory (destructive).

gaia memory forget <user> [options]

Option	Description
`--yes`, `-y`	Skip the confirmation.

`gaia memory list`

List what gaia remembers about a user long-term.

gaia memory list <user>

`gaia model`

Configure the LLM: pick a provider, authenticate (API key or ChatGPT sign-in), pick a model.

gaia model [options]

Option	Description
`--provider`	Model provider: openai
`--oauth`	OpenAI: Sign in with ChatGPT (not an API key).
`--api-key`	API key (non-interactive).
`--model`	Model id (e.g. gpt-4o, gemini-2.5-flash).

`gaia monitor`

Run gaia’s self-monitoring (error-log triage).

`gaia monitor run`

Run one monitor cycle now. Default reports new findings (DM admin); --dry-run previews.

gaia monitor run [options]

Option	Description
`--dry-run`	Analyze and print findings without reporting.

`gaia msg`

Send one message through the multi-user dispatcher and print the reply.

gaia msg <text> [options]

Option	Description
`--user`	The SENDER id (not a role), e.g. ‘972…@s.whatsapp.net’ or ‘12345’.
`--channel`	Channel the sender is on (whatsapp/telegram/cli).
`--name`	Display name for a first-seen sender.

`gaia report`

Bundle the latest crash + recent logs + your environment into a GitHub bug report.

gaia report [options]

Option	Description
`--all`	Include every crash report, not just the last.
`--no-open`	Print the URL instead of opening a browser.

`gaia restart`

Restart the daemon (stop if running, then start).

gaia restart [options]

Option	Description
`--timeout`	Seconds to wait for graceful shutdown before SIGKILL.

`gaia serve`

Run the background connectors in the foreground (what the daemon executes).

gaia serve [options]

Option	Description
`--hold`	Keep running with zero connectors (testing / service debugging).

`gaia service`

Run gaia as a boot service (launchd on macOS, systemd –user on Linux).

`gaia service install`

Install + start the service (runs at login, restarts on crash).

gaia service install

`gaia service status`

Show the service state (defers to launchctl / systemctl).

gaia service status

`gaia service uninstall`

Stop + remove the service.

gaia service uninstall

`gaia setup`

Configure gaia: model, connectors, search, tools.

gaia setup

`gaia skill`

List, author, install, and manage skills.

`gaia skill install`

Install skill(s) from a local folder or a git repo into the skills dir.

gaia skill install <source> [options]

Option	Description
`--name`	Rename the id (single-skill installs only).
`--force`	Overwrite existing skill(s).

`gaia skill list`

List every installed skill (id + description).

gaia skill list

`gaia skill new`

Author a new skill — manually, from a file, or drafted by a model (–from).

gaia skill new <name> [options]

Option	Description
`--description`	One-line description.
`--instruction-file`	Read the SKILL.md body from this file.
`--from`	Have a model draft the skill from this one-line brief.
`--force`	Overwrite existing skill(s).

`gaia skill rm`

Delete skills by id, glob (huashu-*), or ‘all’.

gaia skill rm <patterns> [options]

Option	Description
`--yes`, `-y`	Skip the confirmation.

`gaia skill show`

Print a skill’s description and full instructions (SKILL.md body).

gaia skill show <skill_id>

`gaia soul`

Create, inspect, and manage reusable souls.

`gaia soul edit`

Open a soul’s Markdown in $EDITOR, re-validate it on save, and store it.

gaia soul edit <key>

`gaia soul list`

List every stored soul (key, name, model, description).

gaia soul list

`gaia soul new`

Create a soul — manually (no model key) or, with –ai, via the soul-smith.

gaia soul new <name> [options]

Option	Description
`--description`	What the soul is for.
`--instruction`	The soul’s system prompt.
`--instruction-file`	Read the instruction from this file instead.
`--model`	Model id (default: config llm.model).
`--skill`	Skill id (repeatable).
`--tool`	Tool id to pin (repeatable).
`--style`	Voice (default: config default_communication_style).
`--ai`	Let the soul-smith author the spec from this TASK (needs a model key).
`--force`	Overwrite an existing soul with the same key.
`--no-input`	Never prompt; fail if a field is missing.
`--yes`, `-y`	With –ai: skip confirmation prompts.

`gaia soul rm`

Delete a soul by key (asks for confirmation unless –force).

gaia soul rm <key> [options]

Option	Description
`--force`	Delete without confirmation.

`gaia soul show`

Print every field of one soul (raw JSON with –json).

gaia soul show <key>

`gaia start`

Start the daemon in the background (see ‘gaia status’ / ‘gaia stop’).

gaia start

`gaia status`

Show daemon state: pid, uptime, connectors, model, log paths.

gaia status

`gaia stop`

Stop the running daemon (SIGTERM, then SIGKILL after –timeout).

gaia stop [options]

Option	Description
`--timeout`	Seconds to wait for graceful shutdown before SIGKILL.

`gaia style`

Show or set Gaia’s communication style (voice).

gaia style <name>

`gaia task`

Inspect the missions task board.

`gaia task list`

List tasks on the board (newest first).

gaia task list [options]

Option	Description
`--mission`	Only this mission’s tasks.
`--status`	Only tasks in this status.
`--user`	Only this owner’s tasks.

`gaia task show`

Print one task in full (raw JSON with –json).

gaia task show <task_id>

`gaia tools`

Configure tools: browser, web search, custom MCP servers (and --all to toggle the rest).

gaia tools [options]

Option	Description
`--all`	Enable/disable the optional on/off tools too.

`gaia uninstall`

Remove gaia. Asks before deleting ~/.gaia unless –purge/–keep is given.

gaia uninstall [options]

Option	Description
`--purge`	Also delete ~/.gaia (non-interactive).
`--keep`	Keep ~/.gaia (non-interactive).

`gaia update`

Upgrade gaia in place (re-pull from git); restart the daemon if it’s running.

gaia update [options]

Option	Description
`--ref`	git ref to install (branch/tag/sha).
`--extras`	Extras to install (default: all).

`gaia user`

Manage known users (roles, names, channels).

`gaia user link`

Attach another channel id (‘channel:sender’) to a user.

gaia user link <ref> <identity>

`gaia user list`

List known users — id, name, role, and the channels that reach them.

gaia user list

`gaia user name`

Set a user’s display name.

gaia user name <ref> <name>

`gaia user rm`

Delete a user from the store.

gaia user rm <ref> [options]

Option	Description
`--yes`, `-y`	Skip the confirmation.

`gaia user role`

Set a user’s role (approve a guest).

gaia user role <ref> <role>

`gaia user show`

Print every field of one user (raw JSON with –json).

gaia user show <ref>

`gaia version`

Print the gaia version, Python version, and install location.

gaia version