CLI reference overview¶

gdc provides two command-line programs:

Program	Purpose	Reference
`gdc`	Headless agent runs plus commands to inspect and manage your data.	gdc
`gdc-tui`	The interactive terminal app.	gdc-tui

This section documents every command and flag. For task-oriented guides, see the User guide.

Global options (`gdc`)¶

These apply to any gdc subcommand. Each also has an environment variable; command-line flags take priority. See Environment variables.

Flag	Environment	Description
`--base-url <url>`	`GDC_BASE_URL`	Model endpoint (OpenAI-compatible).
`--model <name>`	`GDC_MODEL`	Model to request.
`--api-key <key>`	`GDC_API_KEY`	API key for hosted endpoints. Kept out of help and error output.
`--config <path>`	`GDC_CONFIG`	Use a specific config file instead of the default cascade.
`--db-path <path>`	`GDC_DB_PATH`	Session database location.
`--session-id <id>`	`GDC_SESSION_ID`	Use a specific session id instead of a fresh one.

gdc --version prints the version; gdc --help and gdc <command> --help print usage.

Command	What it does
`gdc print`	Run the agent (streaming, with tools).
`gdc chat`	Single-shot reply, no tools.
`gdc sessions`	Inspect and manage saved sessions.
`gdc storage`	Bulk data housekeeping.
`gdc permissions`	Inspect and revoke remembered approvals.
`gdc memory`	Manage persistent memory notes.
`gdc mcp`	Manage external tool servers.
`gdc plugins`	Install and manage plugins.
`gdc hooks`	Inspect configured hooks.
`gdc serve`	Run gdc as a server.
`gdc swarm`	Distributed swarm operations (experimental).

Confirmation prompts. Destructive commands (sessions delete, storage gc, permissions revoke, and some swarm operations) ask you to confirm. Pass --yes to skip the prompt in scripts.
JSON output. Inspection commands accept --json and emit a stable shape suitable for piping into other tools.
Project scope. Data commands default to the current project (found by walking up to a .git marker). Use --all for every project or --cwd <path> to target another one.
No model needed. The data commands (sessions, storage, permissions, memory, plugins, mcp, hooks) don't need a model configured.