Repository navigation
feat(cli): one gaia front door with familiar flags (after v0.25.0) #4891
Description
A new user meets three programs that answer to gaia, and none of them takes the flags people already know from other coding agents. The goal is one front door: gaia behaves the same however it was installed, opens the terminal UI when run bare, sets itself up with a switch, and accepts the common Claude Code-style flags so there is nothing new to learn. Timing: after v0.25.0.
Today
- Python
gaiais the CLI:gaia init,gaia chat, and the rest. Run bare it opens the browser Agent UI;gaia --cliopens the interactive chat. - The npm package's
gaia(@amd-gaia/gaia) is a different program with its own commands (run,fetch,serve,version). It can shadow the Python one onPATH. - The terminal UI is a third binary,
gaia-tui. For setup it shells out to the Python CLI (gaia init --profile … --yes), so the "no Python needed" npm path still needs PythongaiaonPATH. - One-shot use is
gaia chat -q "…". There is no continue or resume flag, no machine-readable output flag, and permissions are set inside the UI.
Phase 1: one command surface
- Bare
gaiaopens the terminal UI from every install. Today a pip install opens the browser Agent UI instead; that moves behindgaia --ui. Every existing subcommand keeps working. - A setup switch:
gaia --initruns the same setupgaia initdoes and then opens the terminal UI, so installers and CI can set up without driving the UI. The in-UI setup gate stays. - The npm launcher stops competing for the name: its integrator commands move under
gaia agent fetch/gaia agent serve, andnpx @amd-gaia/gaiawith no arguments does what baregaiadoes. - Familiar flags, accepted on bare
gaiaand ongaia chat:
| Flag | Meaning | Today |
|---|---|---|
-p, --print "<prompt>" |
Answer once and exit | gaia chat -q |
-c, --continue |
Continue the most recent session | none |
-r, --resume [id] |
Pick or name a session to resume | none |
--model <id> |
Model for this run | gaia config set default_model |
--output-format text|json|stream-json |
Machine-readable output for scripts | none |
--permission-mode <mode> |
Ask, accept edits, or full access for this run | set in the UI |
--dangerously-skip-permissions |
Alias for --permission-mode set to full access, spelled as Claude Code spells it |
none |
--add-dir <path> |
Allow another folder | --allowed-paths |
--append-system-prompt "<text>" |
Add instructions for this run | none |
--max-turns <n> |
Cap the agent's steps | --max-steps |
--mcp-config <file> |
MCP servers for this run | connectors |
--verbose, --debug |
More output | --debug |
-v, --version |
Print the version | -v |
- Each new flag is an alias onto existing behaviour where one exists; the old spelling keeps working and both are documented in
docs/reference/cli.mdx. - A flag GAIA cannot honour is refused with a message naming the alternative, never accepted and ignored.
Phase 2: one binary
Ship setup, the CLI and the terminal UI as one download with no Python prerequisite. Setup and the CLI are Python and the UI is Go, so this means either bundling the frozen Python core with the UI binary or porting setup to Go. Decide after #3923 (folding the chat package into the flagship), which shrinks what has to be bundled.
Decided (2026-10-07)
- Bare
gaiaopens the terminal UI. The browser Agent UI moves behindgaia --ui. This changes what a pip install does today, so it goes in the release notes as a breaking change. - Full access has two spellings and no others.
--permission-modewith full access named, and--dangerously-skip-permissionsas an alias to match Claude Code. No shorter flag. Either one prints the same "full access is on" notice the UI shows. - First cut:
-p,-c,-r,--modeland--output-format. The remaining flags in the table follow in later PRs.
Acceptance criteria
-
gaia --dangerously-skip-permissionsandgaia --permission-modewith full access do exactly the same thing, and both say so on screen. -
gaia,gaia -p "hello",gaia -candgaia --initbehave identically from a pip install, the desktop installer andnpx @amd-gaia/gaia. -
gaia -p "…" --output-format jsonprints one JSON object a script can parse, with the answer, the model, token counts and an error field. -
tests/unit/cli/test_cli_docs_drift.pycovers every new flag, and a CLI integration test runs each one against the real command. - Flagship eval re-run if any flag changes the prompt or the tool list (
--append-system-prompt,--mcp-config).
Related: #3923 (chat package removal), #4890 (container image).
Activity
github-actions commentedon Oct 7, 2026
No duplicate found. Two existing short flags will clash with the proposed table and should be settled before Phase 1 starts:
-palready means--profileongaia init. Ifgaia --inittakes a profile,gaia --init -p npubecomes ambiguous with-pmeaning print. One fix is to give--initonly the long--profileform.-vmeans--verboseongaia email, not--version. It only applies under that subcommand, so it isn't a hard conflict, but it breaks the "nothing new to learn" goal. Worth a decision when the flags are aligned ongaia chat.-cand-rare free on baregaiaand ongaia chattoday, so the first cut (-p,-c,-r,--model,--output-format) has no other collisions.🔍 Technical details
src/gaia/cli.py:3588—init_parser:--profile, -psrc/gaia/cli.py:1388—email_parser:-v, --verbosesrc/gaia/cli.py:1039— top-level-v, --version(already matches the table)src/gaia/cli.py:1220—chat_parser:--query, -q(to be aliased by-p/--print)