> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgauge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Onboard with the Gauge web product or CLI and inspect your first measurements.

You can onboard through the full Gauge web product or the Gauge CLI. Both options let you create Agent Preference and Agent Experience measurements, configure their environments, launch runs, and inspect results.

## Onboard with the web product

To evaluate product changes before merging them, follow [Pull request evaluations](/agents/guides/github-pr-checks). The GitHub App runs committed cases against your candidate package, executable, docs preview, Skills, or files and reports the outcome on the PR.

Sign in at [agents.withgauge.com](https://agents.withgauge.com) and complete the guided onboarding flow. You can create or join an organization, seed starter measurements, configure runs, and review results without installing the CLI.

## Onboard with the CLI

### Prerequisites

Before you begin, install Node.js 22.12 or later.

<Steps>
  <Step title="Install the CLI">
    Install `gauge` from npm.

    ```bash theme={null}
    npm install -g @withgauge/cli
    ```

    This also installs the `gauge-agents` skill for coding agents such as Claude Code and Codex. Run `gauge update` later to get the latest version.
  </Step>

  <Step title="Create or join an organization">
    Run the guided onboarding flow. Gauge opens your browser to sign you in.

    ```bash theme={null}
    gauge onboard
    ```

    The command can create a workspace and seed starter Agent Preference and Agent Experience measurements.
  </Step>

  <Step title="Select an organization">
    List the organizations you can access, then save one as your default.

    ```bash theme={null}
    gauge orgs list
    gauge orgs use acme
    ```
  </Step>

  <Step title="Inspect your setup">
    View the organization summary and its measurements.

    ```bash theme={null}
    gauge status
    gauge preference list
    gauge evals list
    gauge models list
    ```
  </Step>
</Steps>

<Tip>
  Run `gauge --help` or `gauge <command> --help` whenever you need the current options for a command.
</Tip>

## Launch and inspect one eval

After onboarding, check your [billing balance](/agents/guides/billing) and create a small task with an observable outcome:

```bash theme={null}
gauge billing status
gauge evals create \
  --name "Create a greeting file" \
  --text "Create a file named hello.txt containing exactly Hello from Gauge." \
  --criterion "File created: The workspace contains hello.txt with exactly the text Hello from Gauge." \
  --agent claude-code --cadence none --samples 1
```

Copy the eval ID returned by the command and replace `<eval-id>` below. This eval runs only when you ask it to. Start a run with the settings you just saved:

```bash theme={null}
gauge evals run <eval-id>
gauge evals runs <eval-id>
```

Review the run count and confirm when prompted. Copy a run ID from the list, then inspect it:

```bash theme={null}
gauge runs watch <run-id>
gauge runs diff <run-id>
gauge runs insight <run-id>
```

A useful first result includes the recorded session, file change, and judged criterion. Execution success and a passing criterion are separate: wait for judging before reading the eval's pass rate. See [Run troubleshooting](/agents/guides/troubleshooting-runs) if either is missing.

Next, follow [Create and inspect an eval](/agents/guides/create-an-eval-and-run-an-experiment), [configure runs for your codebase](/agents/guides/configure-a-scenario), or [test an improvement](/agents/guides/improve-agent-results).

## Next steps

<CardGroup cols={2}>
  <Card title="Learn how Gauge works" icon="diagram-project" href="/agents/concepts/how-gauge-works">
    Understand measurements, run settings, preference scenarios, and judged
    results.
  </Card>

  <Card title="Automate with the CLI" icon="terminal" href="/agents/guides/cli">
    Use JSON output, environment variables, and declarative specs in CI.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.