Skip to main content
The gauge CLI runs real coding agents against your product, records where they get stuck, and lets you retest fixes before you publish them. Use it for interactive work, repeatable scripts, and CI jobs. Each command runs on one of two backends:

Local

Agents run in Docker on your machine with your own agent credentials. No Gauge account.
  • Supports Skills, npm packages, docs, or static files
  • Your coding agent judges sessions and publishes findings
  • Test working-tree changes before you publish them

Hosted

Agents run on VMs managed by Gauge, and runs use credits. Hosted runs have all the capabilities of local runs, and also add:
  • Support for authenticated APIs and MCPs (credentials held at the gateway)
  • Automatically grouped Friction and Objections
  • Support for custom user personas
  • Shared workspace with team members
  • GitHub App for PR checks
Sections for hosted-only commands are marked Hosted only. Gauge Agents supports Claude Code, Codex CLI, OpenCode, Pi, and Antigravity. Antigravity runs only on hosted Gauge. Run gauge models list to see available agent/model targets for your selected backend. See supported agents and models for configuration guidance.
CLI 0.22.0 replaced the evals, runs, apply, batches, and run-requests command groups, and moved case files to gauge-cases/. If you use 0.21.0 or earlier, see Upgrade from earlier versions.

Install the CLI

The CLI requires Node.js 22.13 or later.
To update the CLI to the latest version:

Install the agent skill

We recommend the gauge-agents skill for coding agents. It tells your agent where to find the CLI’s guidance in future sessions. Run this from your project root:
In a terminal, the installer asks for your coding agent and scope. Project scope adds the skill files to this project; global scope makes the skill available in all projects. When a coding agent runs the command, it installs for that agent in the current project. To choose the agent yourself:
Repeat --agent for more than one agent. --copy copies the files instead of creating symlinks. No Gauge account is needed.

Instructions for your coding agent

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.
If no topic has the name you pass, gauge instructions <command> prints that command’s help.

Set up a workspace

Run gauge init in the project you want to evaluate. Git and a Gauge account are optional.
gauge init creates these files: gauge init adds a .gauge/.gitignore that keeps the directory out of Git. Do not delete .gauge/: it holds your local measurements and their history. Moving the project folder keeps it. A fresh clone starts with an empty .gauge/, so each teammate runs gauge init.

Choose a backend

The CLI uses the first backend it finds:
  1. The --local or --hosted flag on the command.
  2. The workspace setting in .gauge/config.json, written by gauge init --local or gauge init --hosted.
  3. Your user setting, from gauge config set backend hosted.
  4. Local.
Signing in does not change the backend. gauge init --hosted changes only this checkout’s setting. It does not move local evals or history to Gauge, and local and hosted evals have separate IDs.

Sign in

Hosted only Hosted runs need a Gauge account. gauge onboard signs you in and creates or selects a workspace. It writes no files in your project.
Signing in does not select the hosted backend. Account commands such as gauge whoami, gauge orgs list, and gauge auth status work with either backend. Hosted features such as gauge status fail with a message to pass --hosted until you select the hosted backend. If you already have a workspace, sign in with the browser flow:
For SSH or another machine that cannot accept a browser callback, use the device flow:
To provide an existing token without opening a browser, pipe it to the CLI:
Gauge stores credentials in ~/.config/gauge/credentials (under $XDG_CONFIG_HOME when set) with permissions limited to your user. The GAUGE_API_TOKEN environment variable takes precedence over stored credentials.

Use an API key for scripts and CI

Scripts, CI jobs, and servers where nobody can sign in in a browser use an organization API key. Create one in Gauge Chat under Settings → Integrations → API Keys and expose it as GAUGE_API_TOKEN. Give a key that launches runs or changes measurements the write permission; a read-only key can read results and run reports. See Authenticate with the API for details.
An API key implies its organization, so commands need no saved default. gauge auth tokens manages only personal tokens created by older versions of Gauge Agents; the current CLI can’t create new ones.
Treat a Gauge API key like a password. Do not commit it or pass it as a command-line argument that may appear in shell history.

Select an organization

Hosted only One token can access every organization where you are a member. If you belong to only one, gauge auth login sets it as the default.
gauge orgs use saves your default organization as orgId in ~/.config/gauge/config.json. Override it for one command with --org:
To save an organization for a repository, run gauge orgs use acme --project in it. This writes orgId to the project’s gauge.json, which everyone working in the repository shares. The CLI picks the organization from --org, then the run specification, then the project’s gauge.json, then your default.

Set up local runs

Local runs start each session in a new Docker container on your machine. Agent usage is billed through your own provider or subscription. Install the runtime image once:
pull downloads the public runtime image that your CLI release pins. inspect checks Docker and the image without downloading anything. gauge models list shows the agents local runs support and their default models. Local runs need:
  • Docker running Linux containers. On macOS, use Docker Desktop. The image runs natively on Intel, AMD, and Apple Silicon machines. On Windows, run the CLI inside WSL.
  • A Docker daemon on this machine. Sessions bind-mount local files, so a remote Docker server does not work.
  • An agent credential. Use the agent’s own login: claude or ANTHROPIC_API_KEY for Claude Code, and codex login for Codex, Pi, and OpenCode.
To use an API key from a different variable, save a credential profile. A profile stores only the variable name, never the secret:
Providers are anthropic, openai, openai-codex, fireworks, and openrouter. use makes the profile the default for its agent. --profile <name> on gauge run overrides the default for one run. set refuses to overwrite an existing profile unless you pass --replace. gauge local profiles list shows profiles and per-agent defaults, and gauge local profiles remove <name> deletes a profile but keeps the native login. To add system tools such as Python, build a custom image from the standard runtime and pass --runtime-image <image> to gauge run. See the Python example.

Save evals and preference prompts

A saved eval is a task with pass criteria and run settings. A saved preference prompt asks which product an agent chooses. Both keep a stable ID, so runs before and after a change group together. Editing one creates a new revision and keeps its history. Local saved measurements live in .gauge/gauge.sqlite. Hosted ones live in your organization.
A saved eval does not store project inputs. Attach them when you launch: --input <name> selects a named input from gauge.json, and --input <name>=<path> replaces its files. Saved-eval inputs and --dry-run work only on the local backend; for hosted previews and inputs, use case files or a JSON spec. Each launch takes a fresh copy of the input files from your working tree, so after you change your product, run the same eval again.
gauge run --eval and gauge run --preference ask for confirmation. Pass --yes only in automation where you have reviewed the configuration and intended spend. To try other agents or sample counts once, pass --agent and --samples; the saved settings stay the same. To test a proposed CLI command, add --hosted --cli-rules rules.json. It applies validated v3/v4 rules to that launch only, including stubs and replacement commands. It also works with direct prompts, case files, and JSON case specs. No optimization or prior session is required. See Test proposed CLI commands for a complete example, discovery tests, and limits. Settings you leave out of an edit stay the same. Use --clear-* flags to remove them. --tag and --clear-tags manage tags. A new criteria list replaces the whole set; to edit one criterion in place, pass --criteria-file with each criterion’s id. gauge eval rm and gauge preference rm delete a measurement and keep its run history. Preference prompts can run in repository scenarios on either backend; see Configure hosted measurements for the commands. Personas, markets, and schedules are hosted only.

Configure hosted measurements

Hosted only Hosted evals and preference prompts can also use personas, registered skills and MCP servers, stored credentials, markets, and schedules:
Use --cadence none for manual runs or daily|weekly|monthly for recurrence. On a recurring cadence, gauge run --eval moves the next scheduled run to one cadence period after the launch. A preference prompt shares its settings across scenarios, each one repository and persona. Add scenarios, then run all or some of them:
Omit --scenario to run all scenarios and move the next scheduled run to one cadence period from now. Running selected scenarios leaves the schedule unchanged. A preference prompt with zero scenarios does not run on a schedule. Use gauge preference markets to list and track markets. Manage each part of the configuration with its own command group: Credential creation and rotation happen in the web app; see Credentials. To compare another repository or tool setup, duplicate the eval in the app and edit the copy.

Run case files

Case files are Markdown files with the task, run settings, and criteria. Commit them when a task is ready for teammates or CI. gauge run with no flags runs the cases in gauge-cases/. Check the files and preview the run first:
--verify checks the configuration and cases. It needs no login and starts no sessions. Results are yes, no, or unknown; exit 1 means a definite problem, while exit 0 can still contain unknowns. --dry-run shows the sessions a run would start, and in local runs it also checks Docker, the image, and agent credentials. Both backends read your working-tree cases and inputs, including uncommitted edits. Hosted runs upload a copy of the selected inputs. Automatic PR checks read the committed files. To run a subset, pass case paths or globs with --files:
For the case format and automatic pull request checks, see Pull request evaluations.

Run in the background

Local only Ctrl+C cancels the active local sessions and cleans up their containers. To keep a batch running after the CLI exits, use --detach. It prints the batch ID and these commands:
If a run is interrupted, gauge cleanup cleans up the remaining sessions in this project. It keeps results and cached images. If session summaries look wrong, gauge run repair rebuilds them from the saved files without running sessions again.

Run from your own CI or local build

Hosted only Supply built inputs directly to run without the GitHub App. Keep your gauge.json and cases in the working directory, and replace product below with an input name from your configuration:
Store an organization API key with write permission as a CI secret, expose it as GAUGE_API_TOKEN, and use your organization’s slug from gauge orgs in place of acme. CI has no .gauge/ directory, so pass --hosted. Run these commands after your build. Review the plan before enabling --yes in automation.
gauge run wait exits 0 once the request settles, whatever the verdict. Add --check to fail the job unless the verdict is PASSED or MEASURED. For a local batch, --check fails unless every session completed.
Repeat --input name=path for each input: Use a dedicated build directory. Links are rejected, and common credential files and node_modules are excluded. Each input is limited to 512 MiB and 20,000 files. No Git checkout is required when all selected inputs are supplied locally. Inputs without an override keep their configured source. Website previews and private consumer repositories still require their configured access; public consumer repositories and an empty workspace need no GitHub App. wait -o json returns the verdict, session results, criterion explanations, and session links. Configure CI to save results.json even when the command fails. If CI owns the trigger, disable automatic PR checks in Gauge’s GitHub settings to avoid duplicate runs.

Run from a JSON spec

gauge run --apply launches cases from a JSON spec instead of Markdown files. Pass - to read from standard input.
A case spec (cases) works on both backends. A battery spec (prompts) is hosted only; add --format battery to --example or --schema to print it.

Read results

status prints progress once, without waiting; for a local batch, use --batch <batch-id>. get --logs prints the session’s events. diff writes the session’s file changes to standard output. insight shows the findings, criterion results, and product choices. On the hosted backend, gauge run watch <run-id> follows a live session, and gauge run regrade <run-id> judges it again against the current criteria. To read a session’s evidence in detail:
insight shows each finding’s ID and its issue. Pass a finding’s evidence seq to trace to see what happened around it.

Analyze local sessions

Local only Hosted Gauge analyzes each session automatically. For local runs, your coding agent reads the evidence and publishes the analysis:
analysis save checks the file against the schema, then saves its findings, criterion results, and product choices together. Analyzing a session again creates a new revision. gauge run list --unanalyzed lists sessions without a published analysis.

Compare runs

gauge run compare answers before-and-after questions. Each side takes repeatable key=value selectors.
It prints the pass rate, each criterion’s pass rate, and median turns and duration, for all runs and per agent and model. Hosted comparisons also include cost. Local comparisons use the criterion results that your coding agent published. Publish the analysis for both sides first. compare warns when one eval ran under more than one revision; add revision= to pick one.

Query results

gauge query builds reports from your runs. Discover the datasets and fields for the selected backend first:
Locally, the datasets are runs and findings. Hosted Gauge adds more reporting datasets, such as ecosystem. A field that the backend does not support fails with an error, not a zero. Use --explain to print the compiled query to standard error. To search local transcripts for a phrase:

Improve results

Hosted only An issue is the same finding across many sessions: friction agents hit, or objections they raised when they chose another product. Rank issues by the number of sessions they affect:
Mark an issue fixed after you ship a change for it. Gauge reopens it when a later run shows it again. To check a fix first, rerun past sessions of the issue. recheck only previews the runs until you add --confirm:
See Manage issues. An optimization edits the pages, Skills, and CLI rules agents used, then reruns those sessions with the edits:
See Improve agent experience and Improve agent preference for the full loop. For a coding agent, run gauge instructions issues and gauge instructions optimization.

Read Gauge Chat data

Gauge account gauge chat works with Gauge Chat AI visibility data. It reads categories, brands, sampled answers, and cited pages, and manages tracked topics, prompts, and tags, for example gauge chat prompts add and gauge chat topics create. Run gauge chat --help for every command. The same sign-in and organization selection apply; an API key uses its own organization.
Category commands take --category (a slug or cat_ ID). Without it, they use the default you set with gauge chat categories use <category>, else the organization’s only category. Date ranges use YYYY-MM-DD and cover at most 92 days. --all follows every page, up to --max items (5,000 by default); in JSON output a non-null nextCursor means more remain. Chat requests are limited to 600 per minute and queries to 60 per minute, per key or sign-in and organization. Exit code 3 means a plan limit blocked the request.

Script with JSON output

Read commands support --output json or -o json. With -o json, errors are a JSON object on standard error.
The output format is a global option, so place it before or after the command unless a shell wrapper requires otherwise.

Environment and config

Manage user values with gauge config get, gauge config set, and gauge config unset. The config directory moves to $XDG_CONFIG_HOME/gauge when that variable is set. Older CLIs saved the default organization as defaultOrg; gauge orgs use replaces it. The workspace backend in .gauge/config.json takes precedence over the user backend.

Telemetry

The CLI sends anonymous command usage to Gauge by default. Each event contains only the command name, a timestamp, the CLI version, and a random installation ID. It never includes arguments, file paths, prompts, file contents, or account details. To opt out:
Set GAUGE_TELEMETRY_DISABLED=1 to opt out for one process or CI job. The variable overrides the saved setting.

Exit codes

Errors print a hint when one exists and a link to the docs. To report a problem with the CLI, run gauge feedback --message "<text>". This works without an account. For failed or incomplete runs, see Run troubleshooting. For credit usage and recovery, see Billing and credits.

Discover commands

gauge --help groups commands by task and shows which groups need a Gauge account. Upgrade with gauge update, and use --help to check the commands available in your installed version.

Upgrade from earlier versions

The old command groups have no aliases. Update scripts, CI jobs, and case folders when you upgrade.
gauge run wait exits 0 whatever the verdict. gauge run-requests wait exited 1 on a failed evaluation. Add --check to CI jobs that must fail.
The default case folder is now gauge-cases/, for the CLI and for PR checks. Rename gauge-evals/ to gauge-cases/, or list your paths in the cases field of gauge.json.
CLI 0.26.0 replaces the optimizations commands. Baselines, rounds, trials, adoption, and handoff are removed, and earlier CLI versions get an update message from the optimizations API. gauge actions is removed. See Improve agent experience for the new loop.