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

# CLI

> Use the Arga CLI to authenticate and run validation workflows

The `arga` CLI gives you a local entry point into Arga. You can use it to:

* authenticate your machine with Arga
* start preview and test-runner workflows from the terminal
* manage scenarios, saved tests, live browser runs, PR checks, sandboxes, and twins
* validate and summarize agent-editable TestConfig JSON

## Install the CLI

Install `arga-cli` with `uv`:

```bash theme={null}
uv tool install arga-cli
```

If you prefer raw pip: `pipx install arga-cli` and `pip install arga-cli` also work.

After installation, verify the command is available:

```bash theme={null}
arga --help
```

## Authenticate from the terminal

Use device login to authorize the CLI:

```bash theme={null}
arga login
arga whoami
```

`arga login` opens the browser so you can approve the device. `arga whoami` confirms the saved credential and prints your current GitHub login, email, email verification status, workspace, and billing plan.

To remove the local credential later:

```bash theme={null}
arga logout
```

Each `arga login` creates a device-scoped key. Arga stores that credential at:

```bash theme={null}
~/.config/arga/config.json
```

You can also create API keys from **Settings → API Keys** in the [web app](/web-app) without running the device authorization flow. That design lets you revoke one key without rotating every other local integration.

If you signed up via [email on the get-started page](https://app.argalabs.com/get-started), you receive a **quickstart API key** limited to 5 twin provisions. This is enough to try the wizard and run a few validations. Run `arga login` when you're ready for full access.

## Scan your project

Use `arga wizard` to detect which third-party integrations your project uses, provision digital twins, and rewrite your `.env` to point at them:

```bash theme={null}
arga wizard
```

<Info>`arga wizard` is the current CLI entrypoint. `arga wizard init` still works as a compatibility alias. On older setups without the CLI, use `npx arga-wizard` for the same flow.</Info>

The wizard scans `package.json`, `requirements.txt`, `pyproject.toml`, and `.env*` files for known integration patterns (Stripe, Slack, Discord, Notion, Google Drive, Dropbox, Box, Google Calendar, Waterfall, Unstructured). It backs up your `.env`, provisions twin instances, and rewrites API keys to route through twins.

When `arga.yaml` is present, `arga test-runner runs url` automatically includes the detected twins — no need to specify them manually.

## Verify your email

After you log in with GitHub, you can verify an email address on your Arga account. Email verification is optional but may be required for certain features.

### Request a verification code

From the Arga web app, submit the email address you want to verify. Arga sends a six-digit code to that address. Codes expire after 10 minutes, and you can request a new code once per minute.

<Note>An email address can only be linked to a single Arga account. If the email is already used by another account, the request returns `409 Only one account can use an email address`. Sign in to that account or pick a different email.</Note>

### Confirm the code

Enter the six-digit code you received. You have up to five attempts per code. If you exceed five attempts, request a new code.

Once verified, `arga whoami` includes your confirmed email and shows the verification status.

## Start validations from the CLI

The CLI mirrors the web app's two validation groups:

* `arga previews ...` for preview environments: Sandboxes, PR Checks, and standalone Twins.
* `arga test-runner ...` for reusable browser testing: Scenarios, Tests, and Runs.

Legacy commands such as `arga test url`, `arga validate pr`, and `arga scenarios ...` still work as aliases, but new scripts should use the `previews` and `test-runner` groups.

### Validate a deployed URL

Use `arga test-runner runs url` for a one-off browser run against a deployed app:

```bash theme={null}
arga test-runner runs url --url https://demo-app.com --prompt "test the login flow"
```

<Info>
  **Free plan:** `--prompt` is required for every run. Team plan users can omit it — Arga will auto-plan tests based on the target app. Free plan runs are also limited to Test Runner Runs and 1 digital twin per run. See [Plans and limits](/plans).
</Info>

If the target requires login, pass credentials together:

```bash theme={null}
arga test-runner runs url \
  --url https://demo-app.com \
  --prompt "log in and create an order" \
  --email test@company.com \
  --password supersecret
```

Provide both `--email` and `--password` together, or leave both out.

#### Testing with digital twins

Use `--twins` to provision [digital twins](/concepts/digital-twins) before the run starts. The CLI provisions the twins, prints their base URLs and environment variables, and waits for you to deploy your app against them before running the validation.

```bash theme={null}
arga test-runner runs url \
  --twins slack,stripe \
  --prompt "test the checkout and notification flow"
```

When `--twins` is used without `--url`, the CLI prompts you for the staging URL after provisioning — so you can deploy first and provide the URL once you know it:

```
Provisioning twin instances...
  [1/2] Slack twin .................. ready
  [2/2] Stripe twin ................. ready

Twin environment variables — update your app's config to point at these:

  Slack:
    Base URL: https://slack--a1b2c3.sandbox.argalabs.com
    SLACK_BOT_TOKEN=xoxb-F9SXMECOSFOGYR3XKXWN

  Stripe:
    Base URL: https://stripe--a1b2c3.sandbox.argalabs.com
    STRIPE_SECRET_KEY=sk_test_...

Deploy your app with the environment variables above.
Enter your staging URL: _
```

If you already know your staging URL, pass both `--url` and `--twins` together — the CLI provisions twins, prints the env vars, and waits for you to press Enter before starting the run.

#### Custom run duration

Set a custom run duration with `--ttl` (in minutes):

```bash theme={null}
arga test-runner runs url \
  --url https://demo-app.com \
  --prompt "full regression suite" \
  --ttl 60
```

<Info>`--ttl` is available in CLI v0.1.5+.</Info>

#### Flags

| Flag                             | Default                     | Description                                                                                                                                                                                     |
| -------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--url`                          | —                           | Deployed application URL. Required unless `--twins` is used (in which case you are prompted after provisioning).                                                                                |
| `--prompt`                       | —                           | Natural-language instructions for what to test. Required on Free plan; optional on Team/Paid.                                                                                                   |
| `--twins`                        | —                           | Comma-separated list of digital twins to provision before the run (e.g. `slack,stripe`). The CLI provisions twins, prints their URLs and env vars, and waits for you to deploy before starting. |
| `--scenario`                     | —                           | Scenario ID to pre-seed twins with sample data.                                                                                                                                                 |
| `--email`                        | —                           | Login email for the target app. Must be provided with `--password`.                                                                                                                             |
| `--password`                     | —                           | Login password for the target app. Must be provided with `--email`.                                                                                                                             |
| `--ttl`                          | 60 (Team/Paid) or 10 (Free) | Run duration in minutes. Free plan is fixed at 10 minutes. Team/Paid plans support 1–480 minutes.                                                                                               |
| `--test-config`                  | —                           | Path to a TestConfig JSON file to execute deterministically from launch.                                                                                                                        |
| `--repo`, `--branch`, `--pr-url` | —                           | Optional repository context for diff-aware planning.                                                                                                                                            |
| `--json`                         | off                         | Output result as JSON.                                                                                                                                                                          |

### Validate a pull request

<Note>PR validation requires a Team or Paid plan. Run `arga whoami` to check your current billing plan.</Note>

Use `arga previews pr-checks run` to start a PR validation run:

```bash theme={null}
arga previews pr-checks run --repo arga-labs/validation-server --pr 182
```

To provide additional instructions or context for the validation, pass `--context-notes` <sup>(v0.1.5+)</sup>:

```bash theme={null}
arga previews pr-checks run \
  --repo arga-labs/validation-server \
  --pr 182 \
  --context-notes "focus on the checkout flow changes"
```

### Run a sandbox preview

Use `arga previews sandboxes run` to deploy a branch into an isolated preview environment with selected twins:

```bash theme={null}
arga previews sandboxes run \
  --repo acme/web-app \
  --branch feature/checkout \
  --twins slack,stripe \
  --scenario-id <scenario-id>
```

### Provision standalone twins

Use `arga previews twins provision` when you only need service twins and do not want to deploy app code:

```bash theme={null}
arga previews twins provision --twins slack,jira --ttl 60 --wait
arga previews twins status <run_id>
arga previews twins mcp-config <run_id>
arga previews twins lock <run_id>
```

Use `arga previews twins mcp-config <run_id>` to print MCP server config for MCP-capable provisioned twins, or add `--install` to merge it into detected local agent configs. Use `arga previews twins lock <run_id>` to disable public access for a provisioned twin session without tearing it down.

### Manage test-runner runs

List recent live browser runs, inspect events, rerun a saved config, or send a message into an active run:

```bash theme={null}
arga test-runner runs list
arga test-runner runs get <run_id>
arga test-runner runs logs <run_id>
arga test-runner runs rerun <run_id>
arga test-runner runs message <run_id> "Use test@example.com"
```

### Manage saved tests

```bash theme={null}
arga test-runner tests list --repo acme/web-app
arga test-runner tests get <test_id>
arga test-runner tests create --name "Checkout" --run-id <run_id> --repo acme/web-app --ci
arga test-runner tests import --file saved-test.json
arga test-runner tests export <test_id> --output saved-test.json
arga test-runner tests edit <test_id>
arga test-runner tests run <test_id> --url https://preview.example.com
arga test-runner tests delete <test_id>
```

Saved tests store deterministic TestConfig JSON. They can be attached to repositories for PR Checks or run manually from the CLI.

### Author TestConfig JSON

```bash theme={null}
arga test-runner tests config validate --file test_config.json
arga test-runner tests config summarize --file test_config.json
arga test-runner tests config normalize --file test_config.json --output test_config.json
```

Assertions are intentionally primitive and deterministic:

```json theme={null}
{"type": "text", "contains": "Order confirmed"}
{"type": "url", "contains": "/checkout/success"}
{"type": "visible"}
```

Use `visible` with a selector on the step.

### Manage legacy validation runs

`arga runs ...` remains available for validation/preview run history and worker/runtime logs:

```bash theme={null}
arga runs list --repo acme/web-app --status running
arga runs status <run_id>
arga runs logs <run_id>
arga runs logs <run_id> --errors-only
arga runs cancel <run_id>
```

Use `arga test-runner runs ...` for live browser test-runner history and events.

If you're in a project directory that already contains `.arga-session.json` (for example after using `arga wizard`), you can omit the run ID:

```bash theme={null}
arga runs logs
```

Use `--json` *(v0.1.5+)* for a machine-readable response. The payload includes the run summary plus `worker_logs`, `runtime_logs`, and any `warnings`. Large worker logs may be truncated, so use the [Get run logs](/api-reference/get-get-run-logs) API reference for full field details.

### JSON output for CI and automation

<Info>`--json` is available in CLI v0.1.5+.</Info>

Key commands accept `--json` to emit structured JSON instead of human-readable text. This is useful in CI pipelines, shell scripts, and agent automation where parsing text output is fragile.

```bash theme={null}
# Capture the run ID from a validation
RUN_ID=$(arga test-runner runs url --url https://app.example.com --prompt "test login" --json | jq -r .run_id)

# Poll run status
arga runs status "$RUN_ID" --json | jq .status

# Fetch logs as JSON
arga runs logs "$RUN_ID" --json | jq '.warnings'

# List runs as a JSON array
arga runs list --repo acme/web-app --json | jq '.[].run_id'
```

| Command                           | `--json` output                                                |
| --------------------------------- | -------------------------------------------------------------- |
| `arga test-runner runs url`       | `{"run_id": "...", "status": "..."}`                           |
| `arga previews pr-checks run`     | `{"run_id": "...", "status": "...", "session_id": "..."}`      |
| `arga test-runner tests list`     | Array of saved tests                                           |
| `arga test-runner tests run <id>` | Demo-runner run object                                         |
| `arga runs status <id>`           | Detailed run summary object from the API                       |
| `arga runs logs <id>`             | Run summary plus `worker_logs`, `runtime_logs`, and `warnings` |
| `arga runs list`                  | Array of run summary objects                                   |

### Configure automatic PR validation

Install the GitHub webhook for a repository so Arga validates pull requests automatically:

```bash theme={null}
arga previews pr-checks install acme/web-app
```

View the current validation configuration:

```bash theme={null}
arga previews pr-checks config acme/web-app
```

Update the configuration:

```bash theme={null}
arga previews pr-checks config-set acme/web-app \
  --trigger pr \
  --comments on
```

```bash theme={null}
arga previews pr-checks config-set acme/web-app \
  --trigger branch \
  --branch main
```

| Flag         | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| `--trigger`  | Validation trigger mode: `pr` (run on pull requests) or `branch` (run on pushes to a branch). |
| `--branch`   | Branch to monitor when using `branch` trigger mode.                                           |
| `--comments` | Whether to post PR comments with results: `on` or `off`.                                      |

### Git helpers

Use `--skip` to mark a commit so that Arga's automatic CI validation skips it.

**In v0.1.0**, `arga commit --skip` amends the HEAD commit to append a skip trailer. Create the commit with `git commit` first, then mark it:

```bash theme={null}
git commit -m "quick typo fix"
arga commit --skip
```

`arga push --skip` verifies the HEAD commit has the skip trailer before pushing — if it doesn't, it exits with an error.

```bash theme={null}
arga push --skip
```

<Info>
  **In v0.1.5+**, `arga commit` wraps `git commit` and passes all extra arguments through. You can combine them in a single command:

  ```bash theme={null}
  arga commit --skip -m "quick typo fix"
  ```

  Without `--skip`, both `arga commit` and `arga push` pass all arguments through to `git commit` and `git push` unchanged.
</Info>

### Manage digital twins

Use `arga previews twins ...` for quick standalone provisioning. Use `arga wizard ...` when you want project scanning and `.env` rewriting.

Twin lifecycle management is handled through `arga wizard` subcommands:

```bash theme={null}
# Run the quickstart wizard to detect integrations and provision twins
arga wizard

# Check twin session health
arga wizard status

# Reset all twins to their seed state
arga wizard reset

# Extend the current session by 10 minutes
arga wizard extend

# Destroy the session and clean up
arga wizard teardown

# Re-run the .env rewriting step
arga wizard env
```

The wizard backs up your `.env` to `.env.arga-backup`, provisions twins, and rewrites API keys to route through them. Restore your original environment with `cp .env.arga-backup .env`.

## Use a custom API URL

By default, the CLI targets `https://api.argalabs.com`.

To point it at a different environment, pass `--api-url`:

```bash theme={null}
arga login --api-url http://localhost:8000
arga test-runner runs url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
arga previews pr-checks run --api-url http://localhost:8000 --repo arga-labs/validation-server --pr 182
```

You can also set `ARGA_API_URL`:

```bash theme={null}
export ARGA_API_URL=http://localhost:8000
arga login
```

## When to use the CLI vs the app

* Use the web app when you want to browse runs, configure repositories, watch the live browser, or edit blocks visually.
* Use the CLI when you want to kick off validations quickly from a terminal, script workflows, or work with TestConfig JSON.
* Use TestConfig JSON when you want coding agents to create or edit deterministic saved tests.
* Use [MCP](/mcp) when you want Cursor, Claude Code, or Codex to query Arga directly from your editor.