gdc

gdc [OPTIONS] <COMMAND>

See Global options for model, configuration and database settings.

Group	Commands
Agent	print, chat
Sessions and data	sessions, storage, permissions, memory
Extensions	mcp, plugins, hooks
Server and swarm	serve, swarm

gdc print

Run the agent with tools. Replies stream to stdout; progress goes to stderr.

gdc print "<task>"

Flag	Default	Effect
--max-tokens N	Provider/config value	Maximum reply tokens
--temperature F	Provider/config value	Sampling temperature
--timeout-secs N	300	Model-request timeout
--max-iterations N	16	Agent iteration limit
--max-tool-call-repeats N	3	Stop after repeated identical calls; 0 disables
--show-reasoning	Off	Stream reasoning to stderr
--system TEXT	Built-in instructions	Override system prompt
--profile NAME	default	Initial agent profile
--output-style NAME	Config default	Reply style
--resume	Off	Reload history; requires an existing --session-id
--auto-approve	Off	Allow requests classified as ask
--auto-approve-remember	Off	Persist approvals; requires --auto-approve
--no-grant-mirror	Off	Keep grants in SQLite without mirroring into project config
--repair-empty-turn	Off	Re-prompt after an empty assistant turn

See Headless CLI.

gdc chat

One non-streaming reply without tools or persistence.

gdc chat "<prompt>"

Flag	Default	Effect
--max-tokens N	Provider/config value	Maximum reply tokens
--temperature F	Provider/config value	Sampling temperature
--timeout-secs N	120	Request timeout

gdc sessions

Inspect and delete saved sessions in the selected database.

gdc sessions list

gdc sessions list

Flag	Default	Effect
--limit N	20	Maximum rows
--all	Off	Every project in this database; conflicts with --cwd
--cwd PATH	Current project	Project filter
--root-only	Off	Hide child sessions
--tree	Off	Parent/child tree; conflicts with --root-only
--all-projects	Off	Scan per-project databases; conflicts with --cwd

Output is a text table or tree. This command has no --json flag.

gdc sessions show

gdc sessions show <id>

Flag	Effect
--limit N	Last N messages; default all
--json	JSON session object
--with-audit	Include compaction history

gdc sessions delete

gdc sessions delete <id> [--yes]

Removes dependent message and tool records. --yes skips confirmation.

gdc storage

gdc storage gc

gdc storage gc <days> [--dry-run] [--yes]

Argument/flag	Effect
<days>	Delete sessions older than this age; 0 uses the current time
--dry-run	Print the count without deletion
--yes	Skip confirmation

gdc permissions

Inspect and revoke project-scoped remembered grants.

gdc permissions list

gdc permissions list

Flag	Effect
--all	Every project's grants; conflicts with --cwd
--cwd PATH	Project scope; default current project
--server NAME	Filter MCP server qualifier
--json	JSON array

gdc permissions revoke

gdc permissions revoke <permission> <pattern>
gdc permissions revoke --all

Flag	Effect
--all	Revoke every grant in scope; conflicts with positional arguments and --server
--server NAME	Qualify one MCP grant
--cwd PATH	Project scope
--yes	Skip confirmation

An absent grant exits successfully with a notice. Revocation removes stored grants; review any separate config allow rules as well.

gdc memory

gdc memory list [--scope <scope>] [--cwd <path>] [--json]
gdc memory search <pattern> [--scope <scope>] [--cwd <path>] [--json]
gdc memory show <name> [--scope <scope>] [--cwd <path>] [--json]
gdc memory write <name> --description <text> --type <type> --scope <scope> --content <text>
gdc memory delete <name> --scope <scope>

Flag	Commands	Effect
--cwd PATH	All	Project directory
--scope SCOPE	All	user, project, local; required for write/delete
--json	list/search/show	JSON output
--description TEXT	write	Required index description
--type TYPE	write	Required: user, feedback, project, reference
--content TEXT	write	Required body; - reads stdin

Search matches name and description case-insensitively. Show uses local > project > user precedence when scope is omitted. Write replaces an existing note. Delete exits with code 1 on a miss.

gdc mcp

gdc mcp list [--json]
gdc mcp add <name> <command> [--arg <arg>]... [--env <K=V>]... [--trusted]
gdc mcp add-http <name> <url> [--auth-header <value>] [--header <K=V>]... [--trusted]
gdc mcp trust <name> [--no]
gdc mcp remove <name>

Flag	Commands	Effect
--cwd PATH	All	Project directory
--scope SCOPE	add/add-http/trust/remove	project (default) or user
--json	list	JSON output
--arg ARG	add	Repeatable process argument; use --arg=--flag for a leading dash
--env KEY=VALUE	add	Repeatable process environment entry
--trusted	add/add-http	Allow tools without approval
--auth-header VALUE	add-http	Authorization header value
--header KEY=VALUE	add-http	Repeatable HTTP header
--no	trust	Set trusted to false

See MCP servers.

gdc plugins

gdc plugins list [--json] [--cwd <path>]
gdc plugins install <source> [--wasm <path>] [--scope user|project] [--force]
gdc plugins remove <name> --scope user|project

Flag	Commands	Effect
--cwd PATH	All	Project directory
--json	list	JSON output
--wasm PATH	install	Override module path; default manifest source
--scope SCOPE	install/remove	Install defaults to user; remove requires scope
--force	install	Replace the installation directory

<source> accepts a manifest or directory. Removal exits with code 1 on a miss. See Plugins.

gdc hooks

gdc hooks list [--json] [--cwd <path>]

Lists plugin and shell hook configuration without invoking handlers.

gdc serve

gdc serve --bind 127.0.0.1:8088

Server options

Flag	Default	Effect
--bind ADDRESS	127.0.0.1:8088	Listen address
--profile NAME	default	Initial agent profile
--output-style NAME	Config value	Default reply style

Swarm roles

Flag	Default	Effect
--role ROLE	Unset	orchestrator, worker, both
--swarm-id ID	Auto-discovery	Select initialized swarm
--orchestrator-endpoint URL	Stored endpoint	Worker coordinator URL
--worker-max-concurrent N	4	Concurrent worker tasks
--review-capable	Off	Advertise review capability
--reviewer-skill NAME	Empty	Repeatable advertised reviewer skill
--strict-review-bind	Off	Require signed review-task binding
--swarm-tls-ca PATH	[swarm].tls_ca	Worker PEM trust bundle

TLS

Flag	Effect
--tls-cert PATH	PEM certificate; requires key; conflicts with ACME
--tls-key PATH	PEM private key; requires certificate; conflicts with ACME
--self-signed-tls	Generate persistent swarm certificate; conflicts with certificate/ACME
--self-signed-san NAME	Repeatable certificate SAN
--acme-domain NAME	Certificate domain; requires contact email
--acme-contact-email EMAIL	ACME account contact; requires domain
--acme-directory URL	CA directory; default Let's Encrypt production
--acme-cache-dir PATH	Cache; default ~/.gdc/tls/<domain>/
--acme-http01-bind ADDRESS	Challenge listener; default 0.0.0.0:80

Non-loopback binds require a role and TLS. See Server setup and TLS.

gdc swarm

Membership and lifecycle

gdc swarm init [--swarm-id <id>] [--bind <address>]
gdc swarm invite [--expires <duration>] [--max-uses <n>] [--role <role>]...
gdc swarm join <url> [--role <role>]... [--tls-ca <path>]
gdc swarm members
gdc swarm status
gdc swarm kick <agent-id> [--reason <text>]
gdc swarm revoke <agent-id> [--reason <text>]
gdc swarm transfer-master <agent-id> --yes
gdc swarm dissolve --yes [--reason <text>]

Flag	Commands	Default/effect
--root PATH	All	Override swarm directory
--swarm-id ID	All except join	Select swarm; init generates an id when omitted
--bind ADDRESS	init	Advertised endpoint; use a worker-reachable address
--expires DURATION	invite	24h; accepts values such as 30m, 2d
--max-uses N	invite	1 authorized join
--role ROLE	invite/join	Repeatable; default worker
--tls-ca PATH	join	PEM trust bundle
--reason TEXT	kick/revoke/dissolve	Operation reason
--yes	transfer-master/dissolve	Required confirmation

Running work

gdc swarm submit "<goal>" [--wait] [--wait-timeout <seconds>]
gdc swarm result <workflow-id>
gdc swarm tasks [--workflow-id <id>]

Flag	Commands	Effect
--wait	submit	Poll until terminal state and print the result
--wait-timeout SECONDS	submit	Wait budget; default 300
--workflow-id ID	tasks	Filter tracked tasks
--orchestrator-endpoint URL	submit/result/tasks	Override stored coordinator endpoint
--tls-ca PATH	submit/result/tasks	PEM trust bundle; also GDC_SWARM_TLS_CA
--root PATH, --swarm-id ID	submit/result/tasks	Select local swarm identity

See Setup, Running work and Operations.