Arga CLI

arga is the command-line interface for authenticating with Arga, installing MCP configuration into supported coding agents, and managing Arga previews, scenarios, saved browser tests, and live test runs.

What It Does

• Authenticates your machine with Arga using the device login flow.
• Stores a device-scoped API key locally so each terminal/device can be revoked independently.
• Shows the currently authenticated user and workspace.
• Installs MCP configuration into supported local agents.
• Starts preview runs for URLs, PR checks, sandboxes, and twins.
• Manages test-runner scenarios, saved tests, blocks, and run history.
• Imports, exports, validates, and summarizes agent-editable TestConfig JSON.
• Wraps git commit and git push with Arga skip-validation helpers.

Installation

Once published to PyPI:

uv tool install arga-cli

You can also install it with pipx or pip:

pipx install arga-cli
pip install arga-cli

After installation, the executable is:

arga --help

Quick Start

Authenticate:

arga login
arga whoami

Remove the saved device credential:

arga logout

Install MCP configuration for detected agents:

arga mcp install

Start a browser URL run:

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

Start a PR check preview:

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

Run a sandbox preview for a branch:

arga previews sandboxes run --repo arga-labs/app --branch feature/demo --twins slack,jira,linear
arga previews sandboxes status <sandbox_id>
arga previews sandboxes logs <sandbox_id>
arga previews sandboxes teardown <sandbox_id>

Provision twins directly:

arga previews twins list
arga previews twins provision --twins salesforce,gitlab,linear,waterfall --ttl 60 --wait
arga twin-runs create --twins google_drive,google_docs,google_sheets --ttl 60 --wait
arga previews twins status <run_id>
arga previews twins extend <run_id> --ttl 90
arga previews twins lock <run_id>
arga previews twins reset <run_id>
arga previews twins teardown <run_id>

Create and run saved tests:

arga test-runner tests create --name "Checkout" --run-id <demo_run_id> --repo arga-labs/app --ci
arga test-runner tests run <test_id> --url https://preview.example.com
arga test-runner tests run <test_id> --sandbox-id <sandbox_id>

Any of these commands accept --json for machine-parseable output:

arga test-runner runs url --url https://demo-app.com --prompt "test login" --json
arga test-runner tests list --json
arga test-runner runs get <run_id> --json

Create a commit that skips Arga validation:

arga commit -m "docs: update examples" --skip
arga push --skip

Inspect or update automatic validation settings:

arga previews pr-checks install arga-labs/validation-server
arga previews pr-checks config arga-labs/validation-server --trigger branch
arga previews pr-checks config-set arga-labs/validation-server --trigger branch --branch main --comments on
arga previews pr-checks enabled
arga previews pr-checks disable arga-labs/validation-server --trigger branch

List and inspect recent validation runs:

arga runs list --repo arga-labs/validation-server --limit 20
arga runs status <run_id>
arga runs logs <run_id>
arga runs cancel <run_id>

Command Reference

Authentication

arga login
arga whoami
arga logout

• arga login opens the browser to complete Arga's device authorization flow.
• arga whoami verifies the saved API key and prints the GitHub login plus workspace.
• arga logout removes the local credential and attempts to revoke the current device on the server.

Previews

arga previews sandboxes run --repo arga-labs/app --branch feature/demo
arga previews sandboxes status <sandbox_id>
arga previews sandboxes logs <sandbox_id>
arga previews sandboxes teardown <sandbox_id>
arga previews pr-checks run --repo arga-labs/validation-server --pr 182
arga previews twins list
arga previews twins provision --twins slack,jira,linear,gitlab,salesforce,waterfall --ttl 60 --wait
arga twin-runs create --twins google_drive,google_docs,google_sheets --ttl 60 --wait
arga previews twins status <run_id>
arga previews twins extend <run_id> --ttl 90
arga previews twins lock <run_id>
arga previews twins teardown <run_id>
arga previews pr-checks install arga-labs/validation-server
arga previews pr-checks config arga-labs/validation-server --trigger branch
arga previews pr-checks config-set arga-labs/validation-server --trigger branch --branch main --comments on
arga previews pr-checks enabled
arga previews pr-checks enable arga-labs/validation-server --trigger branch
arga previews pr-checks disable arga-labs/validation-server --trigger branch

• arga previews sandboxes run starts a branch-backed or PR-backed sandbox preview. Use --twins, --scenario-id, --ttl, and repeated --env KEY=VALUE entries to shape the environment.
• arga previews sandboxes status/logs/teardown inspect readiness, stream lifecycle events, or end a sandbox preview.
• arga previews pr-checks run starts GitHub-backed PR validation for a repository and pull request number, PR URL, or branch.
• arga previews twins list shows the supported twin catalog from validation-server.
• arga previews twins provision provisions twins without running a browser test. Use --scenario-id or --scenario-prompt to seed them, --private to keep them behind proxy auth, and --candidate-safe to expose only provider data-plane APIs on the public candidate host. Candidate-safe runs hide the twin root/UI, twin-hosted documentation and OpenAPI/schema discovery, and control-plane routes; trusted authenticated admin URLs remain available for seeding and verification.
• Google Drive, Google Docs, and Google Sheets are independent twins. Docs and Sheets each expose their provider-compatible API and an interactive editor UI. Provision all three when a gws workflow crosses service boundaries. Their preset Docs and Sheets resources use matching stable IDs, but mutations do not synchronize between twin processes.
• arga previews twins extend / lock / reset / teardown adjust TTL, disable public access, reset seeded state, or end the quickstart session.
• arga previews pr-checks install/config/config-set/enabled/enable/disable manage automatic PR check settings.

arga validate remains as a compatibility alias for older PR-check commands. New PR-check management commands are available only under arga previews pr-checks.

Test Runner

arga test-runner scenarios list --include-presets
arga test-runner scenarios import --file scenario.json
arga test-runner scenarios delete <scenario_id>
arga test-runner tests list --repo arga-labs/app
arga test-runner tests import --file 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 runs url --url https://demo-app.com --prompt "test login flow"
arga test-runner runs url --sandbox-id <sandbox_id> --prompt "test login flow"
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> --sandbox-id <sandbox_id>
arga test-runner runs message <run_id> "Use test@example.com"

• scenarios supports list/presets/get/create/import/export/update/delete for twin seed scenarios. Human-readable list/create/import/update output includes the server-recorded creation time; JSON output preserves created_at.
• arga test-runner scenarios presets lists built-in presets from the public presets API without requiring login.
• tests supports list/get/create/import/export/edit/delete/run for saved browser tests.
• runs starts URL runs and inspects live demo-runner history/events.
• --sandbox-id can attach URL runs, reruns, and saved-test runs to an existing sandbox preview.
• arga test url and arga scenarios ... remain as compatibility aliases.

TestConfig JSON

Agents should author saved tests by editing 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"} plus a selector on the step

For URL validation, you can optionally provide credentials:

arga test-runner runs url \
  --url https://demo-app.com \
  --prompt "log in and create an order" \
  --email test@company.com \
  --password supersecret

Both --email and --password must be supplied together.

Legacy Validation Runs

arga runs list --repo arga-labs/validation-server --status running --limit 20
arga runs status <run_id>
arga runs logs <run_id>
arga runs cancel <run_id>

• arga runs list shows recent PR and branch validation runs in table form.
• --repo narrows the list to a single repository.
• --status accepts completed, failed, or running. The running filter includes non-terminal states such as queued.
• arga runs status <run_id> prints a detailed summary for a specific run.
• arga runs logs <run_id> prints worker logs plus recent runtime logs for a run you own.
• When you omit <run_id>, arga runs logs falls back to ./.arga-session.json when present, which makes wizard-created twin sessions easy to inspect from the same directory.
• Add --json to arga runs logs for a machine-readable response.
• Add --errors-only to keep only failed worker logs plus warning/error runtime entries.
• arga runs cancel <run_id> cancels the run through the validation API.

Both runs list and runs status accept --json for structured output.

Use arga test-runner runs ... for the newer live browser test-runner run history.

Git Wrappers

arga commit -m "docs: update examples" --skip
arga push --skip

• arga commit delegates to git commit.
• arga commit --skip appends a final [skip arga] paragraph to the commit message so Arga skips validation for that head commit.
• arga push delegates to git push.
• arga push --skip verifies the current HEAD commit already contains [skip arga] before pushing. This is safest when the commit was created with arga commit --skip.

Supported MCP Targets

arga mcp install writes or updates MCP configuration for supported agents when they are detected locally:

• ~/.cursor/mcp.json
• ~/.claude/mcp.json
• ~/.config/codex/mcp.json

The installed server is named arga-context and points to:

<api-url>/mcp

using an Authorization: Bearer <api_key> header generated from your saved CLI login.

MCP Installation

Install or update MCP config after you have logged in:

arga login
arga mcp install

The installer:

• Detects supported local agent config directories.
• Preserves existing mcpServers entries.
• Merges in the generated arga-context server definition.
• Returns a non-zero exit code if no supported targets are detected or if any target cannot be updated.

If you need to add the server manually, the generated config looks like:

{
  "mcpServers": {
    "arga-context": {
      "url": "https://api.argalabs.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

JSON Output

Key commands support --json for use in CI pipelines, shell scripts, and agent automation:

# 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 as JSON
arga runs status "$RUN_ID" --json | jq .status

# List runs as a JSON array
arga runs list --repo arga-labs/validation-server --json | jq '.[].run_id'

# Start PR validation and capture result
arga previews pr-checks run --repo arga-labs/validation-server --pr 182 --json

Commands that support --json:

Example Project

See ArgaLabs/example-app for a complete working example showing how to integrate Arga into a Next.js project with:

• GitHub Actions CI validation on every PR
• MCP config for Cursor and Claude Code
• A shell script for manual validation
• End-to-end walkthrough in the README

Using A Custom API URL

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

To point it at another environment, pass --api-url or set ARGA_API_URL:

arga login --api-url http://localhost:8000
arga mcp install --api-url http://localhost:8000
arga test url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
arga validate pr --api-url http://localhost:8000 --repo arga-labs/validation-server --pr 182

export ARGA_API_URL=http://localhost:8000
arga login

Local Development

uv sync
uv run pytest
uv run arga --help

To install the current checkout as a shell command:

uv tool install -e .

Releasing

This repo includes a GitHub Actions workflow at .github/workflows/publish.yml for trusted publishing.

One-time setup:

• Create GitHub Environments named testpypi and pypi in the repository settings.
• In TestPyPI, add a Trusted Publisher for this GitHub repository and workflow:
  • owner: ArgaLabs
  • repository: arga-cli
  • workflow: publish.yml
  • environment: testpypi
• In PyPI, add a Trusted Publisher with the same repository and workflow, but environment pypi.

Publishing flow:

• Manual TestPyPI publish: run the Publish Package workflow with repository=testpypi.
• Automatic PyPI publish: push a tag like v0.1.0.
• The workflow verifies that the tag version matches project.version in pyproject.toml, builds the package with uv build, and publishes with uv publish.

Typical release steps:

uv run pytest
git tag v0.1.0
git push origin v0.1.0

Config Storage

The CLI stores its local auth state in:

~/.config/arga/config.json

That file contains the saved API key plus device metadata returned during arga login.