Skip to main content

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

The wizard's .arga-session.json stores run metadata and a reference to your normal CLI login, without copying your API key or proxy token into the project. Status, reset, extend, teardown, and environment updates use the current login, including after credential rotation. If setup used an API key without saving a normal CLI login, the run handle is still saved; run arga login with access to that run before resuming it. Existing sessions with embedded credentials remain readable, and new session writes omit those credentials.

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>

GitHub includes Actions simulation by default. Eligible internal accounts can opt into executing supported workflows in the same GitHub twin:

arga twin-runs create --twins github --execute-github-actions --ttl 60 --wait

Execution automatically makes the run private. It requires enabled internal access and a verified @argalabs.com account. The legacy github_actions twin name remains accepted for compatibility; new workflows should select github.

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.

Choose a generation mode

Use --generation-mode thorough for complex prompt requirements when a longer wait is acceptable. Omit the flag for Fast generation, or pass --generation-mode fast explicitly.

arga scenarios create \
  --name "Support escalation" \
  --prompt "A Slack support channel with linked escalation threads and consistent message authors" \
  --twin slack \
  --generation-mode thorough \
  --json

arga twin-runs create \
  --twins slack \
  --scenario-prompt "A support channel with linked escalation threads and consistent message authors" \
  --generation-mode thorough \
  --wait --json

Scenario import and update also accept the flag. It overrides generation_mode in the JSON file; without the flag, the file's value is preserved. To regenerate a saved scenario, provide prompt in the update file and omit seed_config:

{
  "prompt": "A Slack support channel with linked escalation threads and consistent message authors",
  "generation_mode": "thorough"
}
arga scenarios update <scenario-id> --file scenario-update.json --json

The mode applies only to new prompt generation. Saved scenario IDs and explicit seed JSON reuse their existing data. The compatibility commands arga test-runner scenarios ... and arga previews twins provision accept the same flag.

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:

Command JSON shape
arga test-runner runs url {"run_id": "...", "status": "..."}
arga previews pr-checks run {"run_id": "...", "status": "..."}
arga previews twins list Array of twin catalog items
arga previews twins status <id> Full twin provisioning status
arga test-runner tests list Array of saved tests
arga test-runner tests run <id> Demo runner run object
arga runs status <id> Full run object
arga runs list Array of run summaries

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.

Before each release, run uv version --bump patch (or set the intended version with uv version X.Y.Z). Commit both pyproject.toml and uv.lock with the features being released, and merge them before tagging. An already published version cannot distribute later feature changes.

From that merged commit:

uv run pytest
uv build
git tag "v$(uv version --short)"
git push origin "v$(uv version --short)"

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.

Fidelity gap reports

Submit one connector's report as UTF-8 Markdown (up to 256 KiB), using your existing Arga login. The pilot currently supports linear, atlassian, microsoft, and google_workspace when enabled for your account.

arga fidelity-gaps submit report.md --connector linear --json
arga fidelity-gaps get <report-id> --json
arga fidelity-gaps wait <report-id> --until deployed --timeout 7200 --json
arga fidelity-gaps list --json

Include expected and observed behavior, exact API/MCP reproductions, deterministic seed configuration, and provider contract captures where relevant. Keep credentials out of reports. Submission returns immediately; work continues after disconnect. Retrying the same file/context reuses the submission. Use --idempotency-key to set a caller-owned retry key, or --parent <report-id> for another report round.

awaiting_review means candidate verification, CI and comment gates passed. It does not mean deployed. deployed includes the merged revision and verified image identities from a fresh Twin Run. Start a new Twin Run before rerunning evals; existing runs retain their previous images. Record the result with:

arga fidelity-gaps verify <report-id> --revision <deployed-revision> --outcome passed --json
arga fidelity-gaps submit round-2.md --connector linear --parent <report-id> --json

wait prints one final JSON object with --json. Exit 0 means the requested milestone was reached, 1 means the job needs information/engineering attention or another request failed, and 2 means the local polling timeout expired. Timeout never cancels remote work. This feature requires the fidelity repair backend to be enabled.

Metadata

Release files for arga-cli 0.1.23

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for arga-cli 0.1.23
File Size Uploaded Provenance Actions
arga_cli-0.1.23.tar.gz 94.3 kB Without provenance Details for arga_cli-0.1.23.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for arga-cli 0.1.23
File Interpreter ABI Platform Actions
arga_cli-0.1.23-py3-none-any.whl Python 3 none any Details for arga_cli-0.1.23-py3-none-any.whl

Total release size: 158.1 kB

Release files / arga_cli-0.1.23.tar.gz

Download URL arga_cli-0.1.23.tar.gz
Size 94.3 kB
Tags Source
SHA-256 checksum
How to use checksums
515822cde7fd4d6032a594e4e29c7591d5bce2a0fe80e4103ae7ca9dcfad5ee1
BLAKE2b-256 checksum
How to use checksums
af551ab4f84416e3302314d9e36dee5817eef10c2e7e92485e0e9369a0a4eee3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / arga_cli-0.1.23-py3-none-any.whl

Download URL arga_cli-0.1.23-py3-none-any.whl
Size 63.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a6ea3b686f1d5ec31ea337b61b88374a28e1987f5ec56f75ca38b9a858686204
BLAKE2b-256 checksum
How to use checksums
6d9e3e4a439d211ae99002d3b90c6b0da97a81b44bb2b367491867d0f5dc2e72
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for arga-cli 0.1.23

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page