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
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.Install the agent skill
We recommend thegauge-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:
--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
Rungauge 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:- The
--localor--hostedflag on the command. - The workspace setting in
.gauge/config.json, written bygauge init --localorgauge init --hosted. - Your user setting, from
gauge config set backend hosted. - Local.
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.
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:
~/.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 asGAUGE_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.
gauge auth tokens manages only personal tokens created by older versions of Gauge Agents; the current CLI can’t create new ones.
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:
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:
claudeorANTHROPIC_API_KEYfor Claude Code, andcodex loginfor Codex, Pi, and OpenCode.
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.
--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:--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:
--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:
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:
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 yourgauge.json and cases in the working directory, and replace product below with an input name from your configuration:
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.
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.
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.
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:
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:recheck only previews the runs until you add --confirm:
gauge instructions issues and gauge instructions optimization.
Read Gauge Chat data
Gauge accountgauge 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 (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.
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: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.Command changes
Command changes