CLI guide

The gauge CLI is a typed client for the Gauge API. Use it for interactive work, repeatable scripts, and CI jobs. Agent execution stays in Gauge; the CLI only configures and launches work.

Install the CLI

The CLI requires Node.js 22.12 or later.

npm install -g @withgauge/cli
gauge --version

Installing the CLI also installs the gauge-agents skill for coding agents it detects, such as Claude Code and Codex. Set GAUGE_SKIP_SKILL_INSTALL=1 to skip this; CI skips it automatically. If you install with --ignore-scripts, add the skill yourself:

npx --yes [email protected] add gauge-sh/gauge-skills --skill gauge-agents --global --yes

To update the CLI to the latest version:

gauge update

Give your coding agent instructions

gauge instructions prints guidance written for a coding agent that uses the CLI. Run it, or have your agent run it, before the first gauge command. The text ships inside the CLI, so it always matches the commands in your installed version.

gauge instructions                  # overview, setup rules, and a summary of each module
gauge instructions evals            # full guidance for one module
gauge instructions --list           # available modules
gauge instructions evals --install  # save it as a skill in .claude/skills/

The overview covers how to sign in, read JSON output, confirm spend, retry safely, and report results with evidence. Each module has a full page:

Topic	Covers
`evals`	Writing realistic developer tasks and observable pass criteria, choosing models, piloting before you scale, and a complete migration example
`preference`	Investigating why agents choose or reject a product, from single sessions to larger groups of runs
`optimization`	The full optimization loop: diagnose, author a change, launch, and read results

Installed instructions do not update themselves. Run --install again after gauge update. For a local terminal, use the browser flow:

gauge auth login

For SSH or another machine that cannot accept a browser callback, use the device flow:

gauge auth login --device

To provide an existing token without opening a browser, pipe it to the CLI:

printf '%s\n' "$GAUGE_API_TOKEN" | gauge auth login --with-token

Gauge stores credentials in ~/.config/gauge/credentials with permissions limited to your user. The GAUGE_API_TOKEN environment variable takes precedence over stored credentials.

Treat a Gauge API token like a password. Do not commit it or pass it as a command-line argument that may appear in shell history.

Select an organization

One token can access every organization where you are a member.

gauge orgs list
gauge orgs use acme
gauge auth whoami

gauge orgs use writes the default organization to ~/.config/gauge/config.json. Override it for one command with --org:

gauge --org research-lab status

Common workflows

Measure Agent Experience

Each eval saves a task, pass criteria, and run settings. Check those settings before you run it.

gauge evals list
gauge evals get eval_123
gauge evals edit eval_123 --agent claude-code --cadence none --samples 1
gauge evals run eval_123
gauge evals runs eval_123

Run now uses the stored settings and asks for confirmation. On a recurring cadence, the next scheduled run moves to one cadence period after the launch. Pass --yes only in automation where you have reviewed the configuration and intended spend.

Measure Agent Preference

Agent Preference prompts measure which brands agents recommend or adopt.

gauge preference list
gauge preference get prompt_123
gauge preference run prompt_123
gauge stats rankings

Choose models, tools, credentials, and a schedule on the preference prompt. Then add scenarios for the repositories and personas you want to test. Every scenario uses the prompt’s settings.

gauge preference scenarios add prompt_123 --repo https://github.com/acme/api
gauge preference scenarios list prompt_123
gauge preference edit prompt_123 --cadence weekly --samples 3
gauge preference run prompt_123 --scenario <scenario-id>

Omit --scenario to run all scenarios and restart the cadence from now. Running selected scenarios leaves the schedule unchanged. A preference prompt with zero scenarios does not run on a schedule. Use gauge preference --help for prompt creation, markets, and run history.

Configure runs

Set an eval’s environment directly on create or edit. To compare another repository or tool setup, duplicate the eval in the app and edit the copy.

gauge evals edit <eval-id> \
  --repo https://github.com/acme/api \
  --agent claude-code \
  --skill [email protected]

Manage each part of the configuration with its own command group:

Command	Manages
`gauge repos`	Repository catalog and Git metadata
`gauge personas`	Simulated-user personas for evals and preference scenarios
`gauge skills`	Versioned agent skills staged into runs
`gauge mcp`	MCP server definitions prepared for runs
`gauge models list`	Available harness/model targets
`gauge connections list`	Credential IDs accepted by `--connection`; no secrets
`gauge evals edit`	An eval’s configuration, cadence, and samples
`gauge preference edit`	A preference prompt’s shared run settings
`gauge preference scenarios`	A prompt’s repository/persona combinations

Use --cadence none for manual runs or daily|weekly|monthly for recurrence. Settings you leave out of an edit stay the same. Use --clear-* flags to remove them. Credential creation and rotation happen in the web app; see Credentials.

Improve results

Diagnose a measurement and estimate the cost before you start an optimization:

gauge optimizations diagnose --eval <eval-id>
gauge optimizations estimate --eval <eval-id> --target <harness:model>

See Improve agent results for the full loop. For a coding agent, run gauge instructions optimization.

Watch a run

gauge runs list --status running
gauge runs watch run_123
gauge runs logs run_123
gauge runs diff run_123
gauge runs insight run_123

watch follows the live event stream. logs prints the events available so far and exits. diff writes the run’s working-tree diff to standard output.

Apply a declarative configuration

Use gauge apply to launch work from a JSON specification.

gauge apply --example > gauge-battery.json
gauge apply --schema > gauge-battery.schema.json
gauge apply --dry-run -f gauge-battery.json
gauge apply -f gauge-battery.json

Run the dry run first. It shows the resources and runs Gauge would create without applying the change.

Query analytics

Discover the available datasets and fields before you build a report.

gauge query datasets
gauge query fields --dataset ecosystem
gauge query \
  --dataset ecosystem \
  --dimensions brand \
  --metrics installs,install_rate \
  --since 30d \
  --output json

Use --explain to print the compiled query to standard error.

Script with JSON output

Read commands support --output json or -o json.

gauge runs list --status succeeded -o json | jq '.items[].id'

The output format is a global option, so place it before or after the command unless a shell wrapper requires otherwise.

Environment and config

Setting	Purpose	Precedence
`GAUGE_API_TOKEN`	Bearer token for CI or ephemeral environments	Highest
`GAUGE_API_URL`	API base URL override	Higher than local config
`defaultOrg`	Default organization slug or public ID	`~/.config/gauge/config.json`
`apiUrl`	Persisted API base URL override	`~/.config/gauge/config.json`

Manage local values with gauge config get, gauge config set, and gauge config unset.

Exit codes

Code	Meaning
`0`	The command completed successfully.
`1`	The API, network, or another runtime operation failed.
`2`	The command or request was invalid.
`3`	Billing or provider-key requirements blocked the operation.
`4`	Gauge needs your input. `gauge optimizations watch` returns this when it is your turn to author or launch.

For failed or incomplete runs, see Run troubleshooting. For credit usage and recovery, see Billing and credits.

Discover commands

The CLI includes authentication, organizations, members, Agent Preference, evals, models, personas, skills, MCP servers, connections, repositories, runs, optimizations, batches, brands, tags, actions, dashboards, provider keys, billing, usage, statistics, queries, and local configuration. Shared presets/scenarios and shared cycles/schedules are retired. If an older script uses them or --one-off, update it to configure the eval or preference prompt directly. Upgrade with gauge update; use gauge --help to check the commands available in your installed version.

gauge --help
gauge runs --help
gauge runs fork --help

Get started

Concepts

Guides

API reference

Endpoints

Install the CLI

Give your coding agent instructions

Select an organization

Common workflows

Measure Agent Experience

Measure Agent Preference

Configure runs

Improve results

Watch a run

Apply a declarative configuration

Query analytics

Script with JSON output

Environment and config

Exit codes

Discover commands

​Install the CLI

​Give your coding agent instructions

​Sign in

​Select an organization

​Common workflows

​Measure Agent Experience

​Measure Agent Preference

​Configure runs

​Improve results

​Watch a run

​Apply a declarative configuration

​Query analytics

​Script with JSON output

​Environment and config

​Exit codes

​Discover commands

Install the CLI

Give your coding agent instructions

Sign in

Select an organization

Common workflows

Measure Agent Experience

Measure Agent Preference

Configure runs

Improve results

Watch a run

Apply a declarative configuration

Query analytics

Script with JSON output

Environment and config

Exit codes

Discover commands