Skip to content

Headless CLI

gdc print runs the agent without a UI. It's the mode for scripts, automation, and CI: you give it a task, the answer streams to your terminal, and the run is saved like any other session. This page covers the everyday workflow; every flag is in the CLI reference.

The basics

gdc print "list the source files and summarise the project"
  • The agent's reply streams to standard output.
  • Progress and tool activity go to standard error, so you can capture just the answer:
gdc print "print the project version" 2>/dev/null

Approvals in headless runs

By default, gdc print denies any action that would need your approval — because there's no one to ask. This keeps unattended runs safe. For a run that needs to act (edit files, run commands), opt in explicitly:

gdc print --auto-approve "run the tests and fix any failure"

Use --auto-approve only where you trust the environment

It lets the run take sensitive actions without prompting. Prefer running it in a disposable checkout, container, or CI sandbox.

To also remember those approvals for the project (so future runs don't need the flag), add --auto-approve-remember. You can review and roll back what it recorded:

gdc print --auto-approve --auto-approve-remember "..."
gdc permissions list      # inspect what was remembered
gdc permissions revoke --all   # roll it all back

→ Permissions

Continuing a session

Each run is saved with an id (printed in the run's progress output). Pick one up later and keep its context:

gdc print --session-id <id> --resume "now add tests for that change"

Without --resume, reusing an id keeps the same audit log but starts the conversation fresh — useful when you don't want earlier steps replayed into context.

Choosing a profile and style

The same profiles and output styles as the terminal app apply here:

# research only; produce a plan, don't change anything
gdc print --profile plan "plan the caching layer"

# short, direct answers
gdc print --output-style concise "why is this build slow?"

Useful controls

Flag Purpose
--max-iterations N Cap how many tool-using rounds a run may take (default 16).
--timeout-secs N Per-request timeout.
--max-tokens N / --temperature F Standard model controls.
--show-reasoning Also stream the model's thinking to standard error.
--system "..." Replace the default system instructions for this run.

See the CLI reference for the complete list.

A quick connectivity check

Before a real run, confirm your model is reachable with a single-shot, no-tools call:

gdc chat "say hello"

If that returns a reply, your provider settings are correct.

Example: a CI step

#!/usr/bin/env bash
set -euo pipefail

export GDC_BASE_URL="http://localhost:8000/v1"
export GDC_MODEL="my-coding-model"

gdc print --auto-approve --output-style concise \
  "run the linter; fix every warning; leave the working tree building"

Tips

  • Set GDC_BASE_URL, GDC_MODEL, and GDC_API_KEY in the environment so scripts don't hard-code them. See Environment variables.
  • If a local model occasionally returns an empty reply after a tool, add --repair-empty-turn — see Troubleshooting.
  • Inspect what a run did afterwards with gdc sessions show <id>.