gauge

gauge [command] [options]

gauge is the command from the npm package `@withgauge/cli` (gauge-sh/gauge-cli). It runs coding agents against tasks you define, stores the transcripts, and gives you a way to see whether a later change did better. It is meant to be driven by the agent that is editing the project, as well as from the shell.Local mode needs Docker running Linux containers, plus credentials for Claude Code, Codex, Pi, or OpenCode. init --local keeps measurements in `.gauge/`, which should stay uncommitted. --cases adds Markdown cases you can commit. Skills and files are read from the working tree. An npm CLI or SDK under test should be packed first. Gauge installs that tarball in the sandbox.Hosted mode adds docs, authenticated MCP servers, and authenticated APIs. gauge auth login (or --device on a remote terminal) is required for hosted Chat and Agents. gauge onboard picks the workspace.`gauge instructions` is how an agent learns the current command surface. `gauge --help` and `gauge run --help` cover flags this page does not list.

local runtime pull

Download the Docker image pinned to this CLI release. It contains the agent harnesses Gauge runs

Show the local runtime Gauge will use

Create `.gauge/`, including a SQLite database. This does not change tracked files

Also write `gauge.json`, a `gauge-cases/` directory, and a note in `AGENTS.md`

Point this checkout at the hosted backend

Install the Gauge skill so a coding agent can find the CLI's instructions

Sign in for hosted Chat and Agents. --device is the flow without a local browser

Sign in and create or select a workspace

Save an eval in the local database

Execute an eval. --dry-run does not spend a full session. --files limits which case files are included

Compare two local batches

Record findings from a local session. Hosted mode analyzes sessions itself

Show the evidence for a run

List local runs as JSON

Start a choice study instead of a fixed eval

Print the instructions a coding agent should follow. Topics include init, run, eval, preference, and session-analysis

.gauge/

Private workspace: SQLite database, backend preference, and local measurements. Do not commit it

Present when shared cases are enabled. Declares inputs and automation

Optional Markdown cases for measurements you want to share or run in CI

Guidance added by init --cases so an agent can find the cases

This is not ThoughtWorks Gauge, the acceptance-testing tool. Packages named `gauge` in apt, Homebrew, or GitHub releases are usually that other project. This CLI is installed as `@withgauge/cli`.Local runs need a working Docker engine and agent credentials. Usage is billed by the agent provider, not by a Gauge package fee described in the CLI readme..gauge/ holds durable results. Deleting it drops the local history.

Gauge (withgauge) is published by gauge-sh as `@withgauge/cli`. The skill that teaches agents the CLI lives in the companion repository gauge-skills. Product documentation is at docs.withgauge.com.

npm(1), node(1), docker(1)

Source code · Documentation