CLI

The arga CLI authenticates your machine and gives scripts or coding agents access to the same core workflows as the web app.

Install

uv tool install arga-cli
arga --help

You can also use pipx install arga-cli or pip install arga-cli.

Authenticate

arga login
arga whoami

arga login starts the device authorization flow and stores a device-scoped credential in ~/.config/arga/config.json. Run arga logout to remove and revoke the current device credential.

Twin Runs

List the available services:

arga previews twins list

Provision a short-lived Twin Run and wait until it is ready:

arga twin-runs create \
  --twins datadog \
  --ttl 60 \
  --wait

Google Drive, Docs, Sheets, and the grouped Workspace service APIs are separate twins. Provision only what the app uses, or combine them:

arga twin-runs create --twins google_drive --ttl 60 --wait
arga twin-runs create --twins google_docs --ttl 60 --wait
arga twin-runs create --twins google_sheets --ttl 60 --wait
arga twin-runs create --twins google_workspace --ttl 60 --wait
arga twin-runs create --twins google_drive,google_docs,google_sheets --ttl 60 --wait

google_docs and google_sheets are full twins: each provision exposes its provider-compatible API and an interactive editor UI. When you provision any two or more of google_drive, google_docs, and google_sheets under the same Twin Run ID, they share one run-scoped file state. Creates, edits, renames, permissions, revisions, trash, and deletes stay synchronized across the selected twins. Different Twin Run IDs remain isolated. google_workspace contains People, Workspace Events, Apps Script, Pub/Sub, and helper task/push-notification APIs. It does not contain Drive, Docs, Sheets, Gmail, or Calendar. When you use gws, cache each provisioned service’s Discovery document. See Use the Google Workspace CLI with Arga twins for the complete setup. Seed the twins from a saved Scenario:

arga previews twins provision \
  --twins slack,stripe \
  --scenario-id <scenario-id> \
  --ttl 60 \
  --wait

Manage a running environment:

arga previews twins status <run-id>
arga previews twins reset <run-id>
arga previews twins extend <run-id> --ttl 90
arga previews twins lock <run-id>
arga previews twins teardown <run-id>

reset restores the baseline captured when the twins were provisioned.
extend changes the requested TTL within your plan limit.
lock revokes public access while preserving authenticated access.
teardown ends the run immediately.

Configure a local project

Run the wizard from your project directory:

arga wizard

The wizard detects supported provider configuration, backs up .env to .env.arga-backup, provisions selected twins, and replaces provider endpoints or credentials with twin values. Restore the original file with:

cp .env.arga-backup .env

Scenarios

arga test-runner scenarios list --include-presets
arga test-runner scenarios get <scenario-id>
arga test-runner scenarios create \
  --name "Billing customer" \
  --prompt "A Stripe customer with an active annual subscription" \
  --twin stripe
arga test-runner scenarios import --file scenario.json
arga test-runner scenarios export <scenario-id> --output scenario.json
arga test-runner scenarios update <scenario-id> --file scenario.json
arga test-runner scenarios delete <scenario-id>

Use explicit JSON when an agent or fixture needs exact provider state. Use a prompt for faster exploratory setup.

Choose a generation mode

Requires arga-cli 0.1.20 or later. Upgrade with uv tool upgrade arga-cli. 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.

Test Runs

Start a browser run against a reachable URL:

arga test-runner runs url \
  --url https://staging.example.com \
  --prompt "Sign in and verify checkout"

For an authenticated application flow, pass --email and --password together. Inspect and manage run history:

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"

Saved Tests

Create a Saved Test from a Test Run:

arga test-runner tests create \
  --name "Checkout" \
  --run-id <run-id> \
  --repo owner/repo

List, edit, and run saved tests:

arga test-runner tests list --repo owner/repo
arga test-runner tests get <test-id>
arga test-runner tests edit <test-id>
arga test-runner tests run <test-id> --url https://staging.example.com
arga test-runner tests export <test-id> --output checkout-test.json
arga test-runner tests delete <test-id>

Add --ci when creating a test to make it eligible for that repository’s PR Test Runs.

TestConfig JSON

Saved Tests use agent-editable TestConfig JSON. Validate or normalize a file before importing it:

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

TestConfig assertions are deliberately small and deterministic:

{"type":"text","contains":"Order confirmed"}

{"type":"url","contains":"/checkout/success"}

{"type":"visible"}

PR Test Runs

Install and configure repository automation:

arga previews pr-checks install owner/repo
arga previews pr-checks config owner/repo --trigger pr
arga previews pr-checks config-set owner/repo \
  --trigger pr \
  --comments on
arga previews pr-checks enabled

For a branch trigger:

arga previews pr-checks config-set owner/repo \
  --trigger branch \
  --branch main

Pause or resume a configuration:

arga previews pr-checks disable owner/repo --trigger pr
arga previews pr-checks enable owner/repo --trigger pr

Start a run manually:

arga previews pr-checks run --repo owner/repo --pr 42

PR Test Runs use the repository’s configured application target. They do not create a per-PR Arga deployment.

JSON output

Commands that return structured data accept --json:

arga previews twins provision --twins slack --wait --json
arga test-runner runs list --json
arga test-runner tests list --json

Git helpers

Create a commit that skips Arga validation for that head commit:

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

The commit wrapper appends [skip arga]. The push wrapper verifies that the current commit already contains it.

Install MCP

arga mcp install

The installer adds the Arga MCP server to supported local coding agents without removing existing MCP entries. See MCP for the installed files and tool reference.

Custom API URL

Pass --api-url where supported or set ARGA_API_URL:

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

Get started

Digital twins

Tests

Setup

Integrations

Resources

Install

Authenticate

Twin Runs

Configure a local project

Scenarios

Choose a generation mode

Test Runs

Saved Tests

TestConfig JSON

PR Test Runs

JSON output

Git helpers

Install MCP

Custom API URL

​Install

​Authenticate

​Twin Runs

​Configure a local project

​Scenarios

​Choose a generation mode

​Test Runs

​Saved Tests

​TestConfig JSON

​PR Test Runs

​JSON output

​Git helpers

​Install MCP

​Custom API URL

Install

Authenticate

Twin Runs

Configure a local project

Scenarios

Choose a generation mode

Test Runs

Saved Tests

TestConfig JSON

PR Test Runs

JSON output

Git helpers

Install MCP

Custom API URL