Skip to content
Back to search

gauge-cli

:dog: The open-source Gauge CLI. Hillclimb your Skills, CLI, SDK, MCP, API, or Docs to make something agents want.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gauge-sh/gauge-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gauge-sh/gauge-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gauge-sh--gauge-cli/badge.svg)](/listings/gauge-sh--gauge-cli)

HTML

<a href="/listings/gauge-sh--gauge-cli"><img src="/api/listings/gauge-sh--gauge-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Gauge is designed to be used by your coding agent. Point it at this repository and ask it to get started, or follow the steps below in the project you want to improve.

You need Node.js **22.13+**, npm, Docker running Linux containers, and credentials for the agent you want to test. Gauge supports Claude Code, Codex, Pi, and OpenCode. It can use native Claude/Codex logins or API keys; agent usage is billed through your provider or subscription.

1. Install Gauge and its runtime

npm install -g @withgauge/cli
gauge local runtime pull

Gauge downloads the published Docker image pinned to your CLI release. The image contains the agent harnesses and standard development tools.

2. Set up your project

From your project directory (Git is optional):

gauge init --local

This creates a shared `gauge.json` manifest and private `.gauge/` workspace, including a SQLite database and local backend preference. It also adds guidance to `AGENTS.md`. Plain init creates no cases; add `--cases` when you want shared Markdown cases in `gauge-cases/`. Commit the manifest, optional cases, and agent guidance. Keep `.gauge/` private: it contains durable measurements and analyses.

3. Install the skill

The [Gauge skill](https://github.com/gauge-sh/gauge-skills/tree/main/gauge-agents) teaches your coding agent where to find the CLI's instructions:

gauge install-skill

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 377 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Gauge CLI
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/gauge-logo-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="docs/assets/gauge-logo-light.svg">
  5. <img alt="Gauge" src="docs/assets/gauge-logo-light.svg" width="800">
  6. </picture>
  7. [![Package checks](https://github.com/gauge-sh/gauge-cli/actions/workflows/checks.yml/badge.svg?branch=main)](https://github.com/gauge-sh/gauge-cli/actions/workflows/checks.yml)
  8. [![npm version](https://img.shields.io/npm/v/%40withgauge%2Fcli)](https://www.npmjs.com/package/@withgauge/cli)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  10. **An open-source CLI for hillclimbing Agent Experience.**
  11. Make your Skills, CLIs, SDKs, MCPs and docs easier for coding agents to discover and
  12. use. Gauge runs real agents against your product, captures where they get stuck,
  13. and lets your own coding agent test fixes before you publish them.
  14. The full loop runs locally with Docker and your existing agent subscriptions or
  15. API keys. **No Gauge account required.**
  16. [Website](https://www.withgauge.com/agents/) ·
  17. [Documentation](https://docs.withgauge.com/agents) ·
  18. [Hosted Gauge](https://agents.withgauge.com) ·
  19. [npm](https://www.npmjs.com/package/@withgauge/cli) ·
  20. [Changelog](cli/CHANGELOG.md)
  21. ## What does Gauge find?
  22. Gauge runs and analyzes coding sessions to find the issues that coding agents run into.
  23. Common findings include:
  24. - An interactive command blocks a coding agent
  25. - An agent reaches for deprecated commands or outdated API patterns
  26. - A Skill goes unused even when it should help with the task
  27. - An agent confidently claims a limitation that does not exist
  28. - An agent cannot figure out the intended workflow across multiple commands
  29. The right fix might change error messages, Skill content, help text, code,
  30. or documentation. The Gauge CLI lets you validate proposed fixes before release.
  31. ## Quickstart
  32. Gauge is designed to be used by your coding agent. Point it at this repository
  33. and ask it to get started, or follow the steps below in the project you want to
  34. improve.
  35. You need Node.js **22.13+**, npm, Docker running Linux containers, and
  36. credentials for the agent you want to test. Gauge supports Claude Code, Codex,
  37. Pi, and OpenCode. It can use native Claude/Codex logins or API keys; agent usage
  38. is billed through your provider or subscription.
  39. ### 1. Install Gauge and its runtime
  40. ```sh
  41. npm install -g @withgauge/cli
  42. gauge local runtime pull
  43. ```
  44. Gauge downloads the published Docker image pinned to your CLI release. The
  45. image contains the agent harnesses and standard development tools.
  46. ### 2. Set up your project
  47. From your project directory (Git is optional):
  48. ```sh
  49. gauge init --local
  50. ```
  51. This creates a private `.gauge/` workspace, including a SQLite database and
  52. local backend preference. Plain init changes no tracked files. Add `--cases` when
  53. you want shared Markdown cases: it also writes a `gauge.json` manifest,
  54. `gauge-cases/`, and guidance in `AGENTS.md`. Commit those shared files. Keep
  55. `.gauge/` private: it contains durable measurements and analyses.
  56. ### 3. Install the skill
  57. The [Gauge skill](https://github.com/gauge-sh/gauge-skills/tree/main/gauge-agents) teaches your coding agent where to find the CLI's instructions:
  58. ```sh
  59. gauge install-skill
  60. ```
  61. ## How the improvement loop works
  62. Hillclimbing means making a change, measuring whether it helped, and repeating.
  63. 1. **Define realistic tasks.** Your agent saves evals or preference prompts with
  64. stable identities, editable defaults, and observable outcomes. Use optional
  65. Markdown cases for fully specified measurements intended for sharing or CI.
  66. 2. **Test your current product.** In local mode, Gauge starts fresh Docker sessions
  67. and injects the working-tree version of your configured inputs.
  68. Each test agent sees the task and configured inputs within its sandbox.
  69. Local mode supports Skills, SDKs, CLIs, and files. Hosted compute adds support for
  70. docs, authenticated MCPs, and authenticated APIs.
  71. 3. **Find friction.** Gauge normalizes events from Claude Code, Codex, Pi, and
  72. OpenCode into consistent transcripts. In local mode, your agent reads the evidence,
  73. checks the outcome against the criteria, and identifies what slowed or
  74. blocked the task. It publishes structured Findings and judgments through
  75. `gauge run analysis save`. In hosted mode, this analysis happens automatically after each session.
  76. `gauge run insight` shows the evidence.
  77. 4. **Change and retest.** Your agent edits the product or its guidance and reruns
  78. the affected cases against the new artifacts.
  79. 5. **Analyze the evidence.** Check whether the original problem disappeared,
  80. whether the task succeeded, and whether the change introduced new friction.
  81. Skills and file inputs are read from your working tree. For an npm CLI or SDK,
  82. build and pack a new tarball before rerunning. Gauge installs these pre-release
  83. artifacts in the test sessions, so you can validate a fix before publishing it.
  84. The CLI handles execution and evidence collection. In local mode, your coding agent authors
  85. the changes and analyzes the local results.
  86. ## A closer look at an eval
  87. Saved evals and preference prompts live in `.gauge/gauge.sqlite` locally or in
  88. your hosted organization. Shared file-based cases optionally live in `gauge-cases/`;
  89. `gauge.json` declares project inputs and automation. Both measurement sources
  90. support local and hosted execution, with the input differences described below.
  91. Start with a saved local eval; use a shared case when the task is ready for
  92. teammates or CI.
  93. <details>
  94. <summary>Example: test a release-notes Skill</summary>
  95. Create `skills/release-notes/SKILL.md`:
  96. ```markdown
  97. ---
  98. name: release-notes
  99. description: Write release notes for a new version in the team's format.
  100. ---
  101. Write RELEASE-NOTES.md with the version as its title, an Added section for new
  102. features, and a Fixed section for bug fixes. Use one bullet per change.
  103. ```
  104. For a fresh project, use this `gauge.json`:
  105. ```json
  106. {
  107. "version": 2,
  108. "inputs": {
  109. "release-notes": {
  110. "type": "skill",
  111. "path": "skills/release-notes"
  112. }
  113. }
  114. }
  115. ```
  116. Save the task and criteria:
  117. ```sh
  118. gauge eval create --local --name "Release notes" \
  119. --agent codex --samples 1 \
  120. --text "Write the release notes for version 1.2.0. We added dark mode and fixed a login crash." \
  121. --criterion "Team format: RELEASE-NOTES.md has a version 1.2.0 title, dark mode under Added, and the login crash fix under Fixed."
  122. ```
  123. Use the returned eval ID to preview, then launch when ready:
  124. ```sh
  125. gauge run --eval <eval-id> --local --input release-notes --dry-run
  126. gauge run --eval <eval-id> --local --input release-notes
  127. gauge instructions session-analysis --local
  128. ```
  129. The preview checks local readiness without launching an agent. Your coding agent
  130. then reads the session and publishes its analysis. After changing the Skill,
  131. rerun the same eval ID: the new batch snapshots the current input files while
  132. the baseline remains intact. Keep the task, criteria, and model pin fixed,
  133. analyze both batches, then compare:
  134. ```sh
  135. gauge run --eval <eval-id> --local --input release-notes
  136. gauge run compare --local --baseline batch=<before-id> --candidate batch=<after-id>
  137. ```
  138. For a choice study, use `gauge preference create --kind open-ended` with a task
  139. that lets the agent choose its approach, then `gauge run --preference <id>`.
  140. Supplying the Skill measures choice after that exposure, not discovery on the web.
  141. For a shared or automated version of the eval, use the same input configuration
  142. and create `gauge-cases/release-notes/basic.md`:
  143. ```markdown
  144. ---
  145. criteria:
  146. - name: Release notes follow the team format
  147. rubric: RELEASE-NOTES.md has a version 1.2.0 title, dark mode under Added, and the login crash fix under Fixed.
  148. config:
  149. agents:
  150. - agent: CODEX_CLI
  151. sampleCount: 1
  152. inputs: [release-notes]
  153. ---
  154. Write the release notes for version 1.2.0. We added dark mode and fixed a login crash.
  155. ```
  156. This case uses Codex; use `CLAUDE_CODE`, `PI`, or `OPENCODE` to test another
  157. harness with its configured credentials. The agent starts in an empty workspace
  158. with the Skill installed. The task does not explicitly tell it to use the Skill,
  159. so the session also reveals whether it discovers the guidance.
  160. ```sh
  161. gauge run --verify --local
  162. gauge run --dry-run --local
  163. gauge run --local
  164. gauge run list --local -o json
  165. ```
  166. Verification checks the config and cases. The dry run previews the sessions and
  167. checks local runtime and credential readiness. Neither launches an agent.
  168. Results, transcripts, and available diffs stay under `.gauge/`. Have your coding
  169. agent follow `gauge instructions session-analysis --local` to assess each
  170. criterion and report friction with supporting evidence.
  171. After editing the Skill, rerun the case:
  172. ```sh
  173. gauge run --local --files "gauge-cases/release-notes/*.md"
  174. gauge run compare --local --baseline batch=<before-id> --candidate batch=<after-id>
  175. ```
  176. Use the batch IDs printed by the runs. The comparison summarizes completion, available turns/duration, and published
  177. criterion judgments. Read the findings and evidence to determine whether the fix worked.
  178. </details>
  179. ## What is Gauge?
  180. [Gauge](https://www.withgauge.com) helps teams improve how AI agents discover,
  181. choose, and use their products. **Agent Experience** measures whether agents can
  182. successfully use your product. **Agent Preference** examines which tools agents
  183. choose for a task and why.
  184. This CLI puts that work in the terminal where you and your coding agent already
  185. work. Local execution supports the complete evaluate, analyze, fix, and retest
  186. loop. The hosted platform adds managed infrastructure and shared measurement
  187. over time.
  188. ## Local or hosted
  189. Sign in with `gauge auth login` to use hosted Chat and Agents. On a remote
  190. terminal, use `gauge auth login --device`. See [signing in](docs/shared-cli-auth.md)
  191. for help with login and API keys.
  192. | | Local | Hosted Gauge |
  193. | --- | --- | --- |
  194. | Execution | Docker on your machine, using your agent credentials | Managed compute; sessions keep running when you close your laptop |
  195. | Results and analysis | File evidence; SQLite measurements, judgments, and Findings authored by your coding agent | Shared results, automated judging, and tracking over time |
  196. | Queries | Run summaries and Findings; supported fields are discoverable | Findings and additional reporting datasets |
  197. | Product inputs | Skills, npm CLIs and SDKs, docs and files, web fixtures | Also native binaries, GitHub-resolved website previews, and authenticated MCPs/APIs |
  198. | Iteration | Test working-tree changes and pre-release artifacts | Also controlled response rewriting and managed optimization trials |
  199. | Automation | CLI scripts and local batches | Also scheduled measurements, GitHub App PR checks, and greater concurrency |
  200. | Account | No Gauge account | Gauge workspace and credits |
  201. [Web fixtures](docs/local-web-fixtures.md) let you test changes to content an
  202. agent encounters, such as a docs page, without publishing them first. They
  203. replace pages or route a site to a preview in both local and hosted runs.
  204. Hosted Gauge's gateway also brokers credentials and can rewrite responses
  205. separately for each session.
  206. Project inputs on saved eval/preference launches, and `--dry-run` for those saved
  207. measurements, are currently local-only. For hosted working-tree input snapshots
  208. and previews, use case files or a case spec with `gauge run --hosted`.
  209. For example, the shared case above supports `gauge run --hosted --dry-run`;
  210. hosted previews contact Gauge and may upload inputs. Local and hosted saved
  211. measurements have separate IDs and storage.
  212. To move a project to hosted execution:
  213. ```sh
  214. gauge onboard
  215. gauge init --hosted
  216. gauge instructions --hosted
  217. ```
  218. `gauge onboard` signs you in and creates or selects a workspace.
  219. `gauge init --hosted` changes this checkout's private backend preference; it does
  220. not move local measurements or history into hosted storage. Hosted runs use workspace
  221. credits. See the [documentation](https://docs.withgauge.com/agents) for hosted
  222. setup, PR checks, and optimization workflows.
  223. ## Commands and documentation
  224. The CLI bundles instructions for coding agents, so the guidance matches the
  225. installed version:
  226. ```sh
  227. gauge instructions
  228. gauge instructions init
  229. gauge instructions run
  230. gauge instructions eval
  231. gauge instructions preference
  232. gauge instructions session-analysis
  233. gauge instructions --list
  234. gauge --help
  235. gauge run --help
  236. ```
  237. Use `-o json` on read commands for scripts and agent analysis. Check the runtime
  238. with `gauge local runtime inspect`; configure provider credentials with
  239. `gauge local profiles --help`. Update the CLI with `gauge update`.
  240. See the [CLI reference](cli/README.md) for configuration, supported inputs,
  241. credentials, background runs, cleanup, and CI usage.
  242. ## Telemetry
  243. The installed CLI collects command usage by default: command name, timestamp,
  244. CLI version, and a random installation ID. It excludes arguments, prompts, file
  245. contents, and account identifiers. Disable collection with:
  246. ```sh
  247. gauge telemetry disable
  248. ```
  249. Or set `GAUGE_TELEMETRY_DISABLED=1` for a process or CI environment. See
  250. [telemetry details](cli/README.md#anonymous-cli-telemetry) for storage, delivery,
  251. and the distinction from authenticated API usage analytics.
  252. ## Development
  253. From the repository root:
  254. ```sh
  255. npm ci
  256. npm ci --prefix cli
  257. npm run check
  258. ```
  259. `check` builds, typechecks, runs tests, and verifies packaged installs. It does
  260. not require a Gauge account, Docker, a database, or another repository checkout.
  261. | Directory | Contents |
  262. | --- | --- |
  263. | [`cli/`](cli) | CLI commands, bundled agent instructions, and API schemas |
  264. | [`packages/local/`](packages/local) | Local Docker session runner and runtime Dockerfile |
  265. | [`packages/agent-adapters/`](packages/agent-adapters) | Agent transports and evidence decoding |
  266. For a CLI development loop after building, use
  267. `npm run dev --prefix cli -- --help`.
  268. Docker integration checks run in the [custom runtime workflow](.github/workflows/custom-runtime.yml).
  269. The [runtime](.github/workflows/publish-runtime.yml) and
  270. [CLI](.github/workflows/publish-cli.yml) release workflows validate and publish
  271. versioned artifacts. Runtime releases produce a qualified manifest; commit it as
  272. `cli/runtime-manifest.json` before releasing the CLI.
  273. The shared libraries also have public npm releases, published by the
  274. [agent adapters](.github/workflows/publish-agent-adapters.yml) and
  275. [local execution](.github/workflows/publish-local-execution.yml) workflows from
  276. `gauge-sh/gauge-cli`. Each package's npm trusted publisher must point to that
  277. repository and its matching workflow.
  278. See [Releasing](RELEASING.md) for repository setup, package permissions,
  279. and the runtime-to-CLI release sequence.
  280. ## Support and contributions
  281. Issues are welcome. Forking and building your own version is the preferred way
  282. to customize Gauge. Only the Gauge team merges changes into this repository;
  283. we periodically consider bringing community changes upstream. See
  284. [CONTRIBUTING.md](CONTRIBUTING.md).
  285. For account questions or private reports, contact
  286. [support@withgauge.com](mailto:support@withgauge.com).
  287. ## License
  288. [MIT](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.