Skip to content

Latest commit

 

History

History
502 lines (406 loc) · 22 KB

cli.md

File metadata and controls

502 lines (406 loc) · 22 KB

CLI reference

Every command and flag on this page was verified against the clap definitions in src/main.rs and by running the binary. When the binary and this page disagree, the binary is authoritative — check codegg --help and codegg <command> --help.

Run codegg --help for the current top-level surface and codegg <command> --help for any subcommand.

Contents

Running without a subcommand

With no subcommand, codegg opens the TUI. These startup forms are the common ones:

codegg                                  # start a new session
codegg -c                               # resume the most recent session
codegg -s <session-id>                  # open a specific session
codegg --fork <session-id>              # fork a session
codegg --no-session                     # ephemeral run, no persistence
codegg -m anthropic/claude-sonnet-4-20250514   # pick a model
codegg -a build                         # pick an agent
codegg --cwd /path/to/project           # choose the workspace
codegg -m anthropic/claude-sonnet-4-20250514 --run "Explain this project"   # one prompt, then exit

--model accepts either provider/model-id or a bare model-id. The provider/model form is unambiguous and is what the examples here use.

Global flags

Flag Meaning
-c, --continue-session Resume the most recent session. Conflicts with --session, --fork, --no-session.
-s, --session <SESSION> Open a specific session.
--fork <FORK> Fork the given session.
--no-session Ephemeral run; nothing is persisted.
-m, --model <MODEL> Override the model.
-a, --agent <AGENT> Override the agent.
-p, --run <PROMPT> Run a single prompt and exit.
-f, --format <text|json> Output format for one-shot mode. --output-format is a compatibility alias. Default text.
-q, --quiet Hide status messages in non-interactive mode.
--cwd <DIRECTORY> Set the working directory before startup. Must exist, or the command fails. Equivalent to launching from that directory.

--cwd chooses the initial workspace. During a session, the model-facing session_working_directory tool can persist a default subdirectory within that workspace; it does not change project identity or the workspace security boundary. Use an authorized launch, fork, or session switch to change roots. | -v | Verbosity: no flag warn, -v info, -vv debug, -vvv+ trace. | | --approval-mode <MODE> | interactive, automatic, or yolo. | | --sandbox <PROFILE> | read-only, workspace-write, or full-host. | | --yolo | Exact alias for --approval-mode yolo. | | --standalone | Run the core in-process, without the singleton daemon. |

Approval mode and sandbox are orthogonal: an automatic approval mode never implies host-level filesystem access. A constrained Bash or Python command is refused when the host cannot apply its OS filesystem sandbox; it is not run without containment. Use full-host only when you intend to opt out of CodeGG filesystem containment. Constrained processes receive private temporary space; shared /tmp and global user caches are not writable grants. Filesystem containment does not isolate network access or every IPC channel; Seatbelt also allows broad reads and preserves descriptors opened before confinement. See architecture/security.md for backend-specific guarantees and limits, and docs/tui.md for approval controls.

Sessions

codegg sessions                    # list sessions for the current project
codegg sessions --archived         # include archived sessions
codegg session <session-id>        # inspect one session
codegg export <session-id>         # export to stdout
codegg export <session-id> -o session.json
codegg import session.json         # import a session

These commands read and write the project-local store at <project>/.codegg/sessions.db. The database is created and migrated on first use — by the TUI, the daemon, or any of these commands — so they work in a project that has never been opened.

Sessions created by the TUI are persistent by default and can be resumed across restarts.

launch

codegg launch --project <project-id>                    # new session, fresh checkout
codegg launch --project <project-id> --branch feature/x  # on a named branch
codegg launch --project <project-id> --base main         # from a base branch or tag
codegg launch --project <project-id> --fork <session-id> # fork history into a new checkout
codegg launch --project <project-id> --worktree <worktree-id>  # use an existing checkout
codegg launch --project <project-id> --idempotency-key k1      # retry-safe launch

codegg launch places a session in an isolated managed checkout. It goes through the daemon, because the daemon owns the durable launch record, the worktree service and the workspace registry.

The launch is idempotent: a retry with the same --idempotency-key and the same request converges on the original launch instead of allocating a second checkout. A retry with the same key and a different request is refused. Without --idempotency-key, every invocation is a distinct launch.

--worktree new (the default) allocates a fresh managed checkout; --worktree <worktree-id> adopts a checkout the caller is already authorized for. --base names a branch or tag to create the checkout from; --branch names the branch to create it on.

Shared-checkout execution is not available: a launch always places the session in its own isolated checkout.

Providers and credentials

codegg providers                    # list providers your config can use
codegg models                       # list models across configured providers
codegg models -p anthropic          # list one provider's models

These read your actual configuration and credentials rather than a static list, so the output changes with what you have configured. See docs/providers.md.

The encrypted credential store:

printf '%s' "$OPENAI_API_KEY" | codegg auth set-key openai
codegg auth status                  # account ids only; never secrets
codegg auth logout openai

auth set-key reads the key from stdin, so it does not appear in shell history. On a fresh profile the first protected write creates a CodeGG-managed master key automatically — no key environment variable is required. See docs/providers.md for the full resolution order.

Configuration and diagnostics

codegg validate                     # validate the auto-detected config
codegg validate --config ./my.jsonc # validate a specific file
codegg edit                         # open the config in $EDITOR
codegg edit --config ./my.jsonc     # open a specific file
codegg edit --project               # open the project-local config
codegg edit --editor hx             # override $VISUAL/$EDITOR
codegg doctor                       # run every diagnostic subsystem
codegg doctor providers             # one subsystem

edit

edit opens a config file in your editor, creating it (and its directory) first if it does not exist so the editor always gets a real path to write.

The editor is resolved in this order:

  1. --editor <cmd>
  2. $VISUAL
  3. $EDITOR
  4. the first of hx, vim, vi, nano found on PATH

$VISUAL outranks $EDITOR per the usual Unix convention, because $VISUAL marks the full-screen editor you prefer for interactive editing while $EDITOR is often left as a line-oriented default. Both may be multi-word or quoted (EDITOR="code --wait", EDITOR="/opt/My Editor/hx"). An editor named by $VISUAL/$EDITOR is used even if it is missing — CodeGG reports the spawn failure rather than silently editing the file in a different program.

Which file gets opened, highest precedence first: --config <path>, then a project config discovered from the working directory (.codegg/codegg.jsonc), then the global config. --project forces the project-local file, creating it if no project config exists yet.

After the editor exits, edit re-reads the file and reports whether it still parses. A parse or validation failure is printed to stderr but does not change the exit status — the edit itself succeeded, and you may still be fixing it. Run codegg validate to confirm.

doctor takes an optional positional subsystem:

Subsystem What it reports
all Everything below (the default).
search eggsearch backend, MCP tool coverage, output caps, provider degradation.
mcp Configured MCP servers and their connection state.
lsp Language-server registry and per-gate exposure state.
deterministic-tools eggsact backend, profile, and tool visibility counts.
providers Configured providers. Read-only; makes no network probes.
credentials Stored credential metadata. Never prints secrets.
installation Owned runfiles, helper/sidecar state, and the sandbox kernel probe.

doctor exits 0 even when it reports problems — read the output rather than the exit code.

--subsystem <name> still parses as a deprecated alias for the positional form. Prefer the positional spelling.

Daemon

codegg daemon status                # is it running, and where
codegg daemon logs                  # tail recent daemon logs
codegg daemon logs --lines 200
codegg daemon start                 # run the daemon (BLOCKS - see below)
codegg daemon stop                  # stop it
codegg daemon attach                # attach the TUI to it
codegg daemon attach --new          # attach with a new session
codegg daemon scratch-usage         # measure the daemon-owned scratch cache
codegg daemon scratch-reclaim --tree <digest>   # dispose of one scratch tree

codegg daemon start runs in the foreground. It acquires the singleton lock, binds the socket, and then stays in the foreground for the life of the daemon — it does not fork or detach. Run it in a separate terminal or background it. If a healthy daemon already holds the lock, the command prints a message and exits 0 rather than starting a second instance.

You rarely need to do this by hand: a plain codegg connects to an existing daemon or starts one automatically. See docs/daemon.md.

Scratch measurement and reclamation

codegg daemon scratch-usage                     # the daemon's last snapshot
codegg daemon scratch-usage --refresh           # take a fresh measurement
codegg daemon scratch-usage --json              # machine-readable report
codegg daemon scratch-reclaim --tree <digest>   # dry run: reports, removes nothing
codegg daemon scratch-reclaim --tree <digest> --apply   # actually remove it

scratch-usage reports the daemon's disposable scratch cache: tree count, total size, age, and whether the reclaim path would accept each tree. The daemon answers from its own snapshot unless --refresh asks for a fresh measurement. scratch-reclaim names a tree by the opaque digest that scratch-usage reports; without --apply it is a dry run that removes nothing. Both commands accept --endpoint and --json.

Non-interactive use

One-shot prompt:

codegg --run "Summarize the changes in this repository"
codegg --run "Summarize the changes" --format json

Structured input for CI, via exec:

printf '%s\n' '{"prompt":"Review this repository","model":"anthropic/claude-sonnet-4-20250514","agent":"build"}' \
  | codegg exec --format json --quiet

The same payload can be passed with --json '<payload>' or read from a file with --file <path> instead of stdin. The object has three optional string fields — prompt (required), model, and agent.

codegg exec --json '{"prompt":"List the public functions in src/lib.rs"}' -q

exec also takes -s <session-id> to resume an existing session, and the same policy flags as the root command:

codegg exec --approval-mode interactive --sandbox read-only --quiet \
  --json '{"prompt":"Summarize src/main.rs"}'

--json-output / -j remain as compatibility aliases for --format json. Without explicit policy flags, exec keeps its legacy permissive behavior for existing CI pipelines — set --approval-mode and --sandbox explicitly if you want a bounded run.

MCP, ACP and plugins

codegg mcp list
codegg mcp add
codegg mcp remove
codegg mcp enable
codegg mcp debug

MCP servers are configured under the mcp key in the config file. See docs/MCP.md.

For editor and harness integration, CodeGG speaks ACP v1 over newline-delimited JSON-RPC on stdio:

codegg acp

Without policy flags, ACP keeps the daemon's current policy. An unattended ACP trial can explicitly request one supported envelope:

CODEGG_DAEMON_HOME=/tmp/codegg-private-lane \
  codegg acp --approval-mode yolo --sandbox workspace-write

Policy flags use the same parser as exec. Explicit ACP overrides require an explicit CODEGG_DAEMON_HOME, are serialized against other ACP policy trials for that root, and fail if the daemon reports a narrower effective policy. Use a private daemon root, as the developer harness does; the override is persisted in that daemon's principal preference store. Explicit deterministic denies, hard-denies, authorization, and sandbox enforcement remain active. Turn failures are returned as JSON-RPC errors, not ACP cancelled results.

The developer-only multi-lane supervisor is not part of the shipped binary. From a CodeGG checkout, build a candidate and run:

cargo build --bin codegg
python3 -m dev.harness_lab doctor --binary target/debug/codegg
python3 -m dev.harness_lab smoke --binary target/debug/codegg --subjects 2
python3 -m dev.harness_lab smoke --binary target/debug/codegg --subjects 2 --unattended-profile workspace-write
python3 -m dev.harness_lab smoke --binary target/debug/codegg --subjects 2 --unattended-profile full-host
python3 -m dev.harness_lab tool-trial --binary target/debug/codegg --profile workspace-write
python3 -m dev.harness_lab tool-trial --binary target/debug/codegg --profile workspace-write --deny-bash
python3 -m dev.harness_lab evaluate --binary target/debug/codegg --suite dev/harness_lab/fixtures/smoke.jsonl --ledger /tmp/codegg-ledger --candidate baseline
python3 -m dev.harness_lab report --ledger /tmp/codegg-ledger
python3 -m dev.harness_lab improve --proposer manual --max-iterations 1 --dry-run

It uses temporary roots outside the checkout by default. The ordinary smoke does not submit a model turn or call a provider; policy-profile runs verify the daemon's requested/effective snapshot but also do not submit a turn. The turn-level fixture uses a loopback OpenAI-compatible provider and the native broker, with explicit-deny coverage. Ledger report/replay/compare run offline. Candidate proposals use a separate linked worktree; OpenCode is version-pinned to the qualified CLI adapter and candidate acceptance still requires build, ACP qualification, and paired-ledger gates. See dev/harness_lab/README.md for the path inventory and platform limits.

Plugins are configured through the plugin config key and managed from the TUI; there is no codegg plugins CLI subcommand. WASM plugin execution requires the plugins Cargo feature. See docs/PLUGINS.md.

Research

codegg research "What changed in SQLite's WAL mode since 3.22?"
codegg research "..." --depth deep --audience engineer --allow-network
Flag Default Meaning
--mode <MODE> narrow-answer Research mode.
--audience <AUDIENCE> human Target audience for the write-up.
--depth <DEPTH> medium Research depth.
--output <OUTPUTS> — Output profile; repeatable.
--source <SOURCES> — local, file:<path>, or url:<https-url>. Repeatable.
--allow-network off Permit network fetching.

Research depends on the eggsearch backend; check codegg doctor search first if a query returns nothing.

Shell completions

codegg completions bash                    # print to stdout
codegg completions zsh -o ~/.zsh/completions   # write _codegg into an existing dir

With no -o/--output, the script is written to stdout, not to a file. --output requires the directory to already exist and names the file per shell (codegg.bash, _codegg, codegg.fish, codegg.ps1, codegg.elv).

Supported shells: bash, elvish, fish, powershell, zsh. The command's own help prose lists only four — elvish appears solely in the possible values line, so trust the value list rather than the sentence.

Upgrade

codegg upgrade

Updates a managed prebuilt installation as a single verified transaction. It does not fetch or run install.sh. Source installs have no managed bundle to upgrade; use cargo install again instead. See docs/install.md.

Tool advisor

The tool-selection advisor is a diagnostic surface, not a runtime switch. It reports the effective discovery policy and runs the offline corpus tooling.

codegg tool-advisor status                    # effective policy and decision backend
codegg tool-advisor status --json
codegg tool-advisor bench                     # keyword baseline over the corpus
codegg tool-advisor bench --bm25 --json        # BM25 variant, machine-readable
codegg tool-advisor bench --dataset <path>    # a specific JSONL dataset
codegg tool-advisor lint --dataset <path>     # corpus floors and split coverage
codegg tool-advisor inspect --model <path>    # an SDM local artifact
codegg tool-advisor data status               # captured-training-data state
codegg tool-advisor data inspect              # captured events as JSON
codegg tool-advisor data export --output <file>
codegg tool-advisor data purge

tool-advisor bench defaults to the reviewed repository corpus when no --dataset is given. tool-advisor inspect needs the optional decision-runtime-sdm Cargo feature and is refused without it. data export requires --output; data purge removes the locally captured events.

Remote server (feature-gated)

Both of these exist only in a build with the server Cargo feature.

codegg server --host 127.0.0.1 --port 3000 --standalone-core
codegg attach http://localhost:3000 --token <token>

codegg server refuses to start unless --standalone-core is given: the HTTP server does not proxy to the singleton daemon. codegg attach is the remote HTTP client; it takes a server URL and an optional --token. The local socket equivalent is codegg daemon attach, which is always available.

Hidden compatibility spellings

These still parse but are hidden from --help. They exist so existing scripts and older configurations keep working; prefer the canonical spelling.

Hidden Canonical
--core-transport inproc|stdio|socket --standalone, --stdio, codegg daemon attach
--stdio (compatibility stdio core transport)
--core-endpoint <URI> --endpoint on codegg daemon subcommands
codegg attach-daemon codegg daemon attach
codegg core-stdio (internal transport)
--output-format <FMT> --format
--json-output / -j --format json
doctor --subsystem <NAME> doctor <NAME>

codegg attach is a different command entirely — it is the feature-gated remote HTTP client, takes a server URL, and only exists in server builds. See docs/daemon.md and architecture/server.md.

Source verification

Checked 2026-10-23 against the clap definitions in src/main.rs (the Cli, Commands, ToolAdvisorCommand, ToolAdvisorDataCommand, AuthSubcommand, DoctorSubsystem, OutputFormat, CoreTransport, and DaemonCommand types) and the MCP subcommand enum in src/mcp/cli.rs.

  • Top-level flags: src/main.rs Cli and ExecutionPolicyArgs (-c/--continue-session, -s/--session, --fork, --no-session, -m/--model, -a/--agent, -p/--run, -f/--format with the --output-format alias, -q/--quiet, --cwd, -v, --approval-mode, --sandbox, --yolo, --standalone).
  • Subcommands: src/main.rs Commands — sessions, session, launch, export, import, providers, models, upgrade, tool-advisor, doctor, auth, validate, edit, exec, acp, completions, mcp, research, daemon, plus the server/attach pair that is gated on the server Cargo feature.
  • daemon start foreground behaviour and the "already running" exit: src/main.rs run_daemon.
  • daemon stop is Unix-only; codegg server refuses to start without --standalone-core (exit code 2): src/main.rs cmd_server.
  • daemon scratch-usage / scratch-reclaim flags (--refresh, --json, --tree, --apply, --endpoint): src/main.rs DaemonCommand.
  • tool-advisor subcommands and the decision-runtime-sdm refusal for inspect: src/main.rs cmd_tool_advisor.
  • doctor subsystem list and the "exits 0 even when it reports problems" behaviour: src/main.rs cmd_doctor.
  • edit target-path precedence, the hx/vim/vi/nano fallback order, and "re-reads the file, does not change the exit status": src/main.rs edit_target_path and cmd_edit.
  • completions supported shells (bash, elvish, fish, powershell, zsh) and the per-shell output file names: src/main.rs cmd_completions.
  • upgrade behaviour (a managed-install transaction, not install.sh): src/upgrade/mod.rs.
  • Session store path <project>/.codegg/sessions.db: crates/codegg-core/src/storage/mod.rs.
  • mcp CLI verbs (list, add, remove, enable, debug) and the --server-type, -c, -a, -u flags: src/mcp/cli.rs.
  • research flags and their defaults: src/main.rs Commands::Research.
  • There is no codegg plugins subcommand and no codegg mcp servers spelling: src/main.rs Commands.