CLI

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:

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:

arga --help

Authenticate from the terminal

Use device login to authorize the CLI:

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:

arga logout

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

~/.config/arga/config.json

You can also create API keys from Settings → API Keys in the 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, 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 init to detect which third-party integrations your project uses, provision digital twins, and rewrite your .env to point at them:

arga wizard init

arga wizard init is available in CLI v0.1.5+. On earlier versions, use npx arga-wizard for the same functionality.

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, 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.

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:

arga test-runner runs url --url https://demo-app.com --prompt "test the login flow"

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.

If the target requires login, pass credentials together:

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 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.

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):

arga test-runner runs url \
  --url https://demo-app.com \
  --prompt "full regression suite" \
  --ttl 60

--ttl is available in CLI v0.1.5+.

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

PR validation requires a Team or Paid plan. Run arga whoami to check your current billing plan.

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

arga previews pr-checks run --repo arga-labs/validation-server --pr 182

To provide additional instructions or context for the validation, pass --context-notes ^(v0.1.5+):

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:

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:

arga previews twins provision --twins slack,jira --ttl 60 --wait
arga previews twins status <run_id>

Manage test-runner runs

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

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

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

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:

{"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:

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 init), you can omit the run ID:

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 for full field details.

JSON output for CI and automation

--json is available in CLI v0.1.5+.

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.

# 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:

arga previews pr-checks install acme/web-app

View the current validation configuration:

arga previews pr-checks config acme/web-app

Update the configuration:

arga previews pr-checks config-set acme/web-app \
  --trigger pr \
  --comments on

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:

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.

arga push --skip

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

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.

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:

# Run the quickstart wizard to detect integrations and provision twins
arga wizard init

# 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:

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:

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 when you want Cursor, Claude Code, or Codex to query Arga directly from your editor.

Get started

Validate

Digital twins

SDKs

Setup

Reference

Install the CLI

Authenticate from the terminal

Scan your project

Verify your email

Request a verification code

Confirm the code

Start validations from the CLI

Validate a deployed URL

Testing with digital twins

Custom run duration

Flags

Validate a pull request

Run a sandbox preview

Provision standalone twins

Manage test-runner runs

Manage saved tests

Author TestConfig JSON

Manage legacy validation runs

JSON output for CI and automation

Configure automatic PR validation

Git helpers

Manage digital twins

Use a custom API URL

When to use the CLI vs the app

Get started

Validate

Digital twins

SDKs

Setup

Reference

Documentation Index

​Install the CLI

​Authenticate from the terminal

​Scan your project

​Verify your email

​Request a verification code

​Confirm the code

​Start validations from the CLI

​Validate a deployed URL

​Testing with digital twins

​Custom run duration

​Flags

​Validate a pull request

​Run a sandbox preview

​Provision standalone twins

​Manage test-runner runs

​Manage saved tests

​Author TestConfig JSON

​Manage legacy validation runs

​JSON output for CI and automation

​Configure automatic PR validation

​Git helpers

​Manage digital twins

​Use a custom API URL

​When to use the CLI vs the app

Install the CLI

Authenticate from the terminal

Scan your project

Verify your email

Request a verification code

Confirm the code

Start validations from the CLI

Validate a deployed URL

Testing with digital twins

Custom run duration

Flags

Validate a pull request

Run a sandbox preview

Provision standalone twins

Manage test-runner runs

Manage saved tests

Author TestConfig JSON

Manage legacy validation runs

JSON output for CI and automation

Configure automatic PR validation

Git helpers

Manage digital twins

Use a custom API URL

When to use the CLI vs the app