Skip to main content
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.

​
Sign in

For a local terminal, use 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 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 use writes the default organization to ~/.config/gauge/config.json. Override it for one command with --org:

​
Common workflows

​
Measure Agent Experience

An eval set defines a task and its judging criteria. A run preset supplies the repository and agent configuration.
Attaching a preset changes scheduled spend. Interactive commands print the per-cycle run count and ask for confirmation. Pass --yes only in automation where you have reviewed the configuration.

​
Measure Agent Preference

Agent Preference prompts measure which brands agents recommend or adopt.
Use gauge preference --help to create prompts, attach presets, manage markets, and inspect run history.

​
Configure runs

Run presets are reusable combinations of repositories, agents, models, personas, skills, and MCP servers.
Manage each part of the configuration with its own command group:

​
Watch a run

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.
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.
Use --explain to print the compiled query to standard error.

​
Script with JSON output

Read commands support --output json or -o json.
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 local values with gauge config get, gauge config set, and gauge config unset.

​
Exit codes

​
Discover commands

The CLI includes command groups for authentication, organizations, members, Agent Preference, evals, presets, personas, skills, MCP servers, cycles, repositories, runs, experiments, batches, brands, tags, actions, dashboards, provider keys, billing, usage, statistics, queries, and local configuration.