Skip to main content

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.

The arga-wizard CLI provisions digital twins for your project and rewrites your environment config so your staging app talks to twins instead of real third-party APIs.

​
Prerequisites

  • Node.js 18+ installed
  • An Arga API key — either a quickstart key from email signup (limited to 5 provisions) or a full-access key via arga login or from Settings → API Keys

​
Run the wizard

1

Launch the wizard

From your project directory:
npx arga-wizard
Or if you already have the Arga CLI installed:
arga wizard init
The CLI version automatically passes your saved API key, so you skip the key prompt.
2

Select your twins

The wizard lists all available twins grouped by type. Pick the services your app integrates with.
? Which API twins do you need? (Space to select, Enter to confirm)
  -- UI Twins (with interactive dashboard) --
  [x] Discord          discord.com, api.discord.com
  [ ] Dropbox          api.dropboxapi.com
  [ ] GitHub           api.github.com, github.com
  [ ] Google Calendar  www.googleapis.com/calendar/v3
  [ ] Google Drive     www.googleapis.com/drive/v3
  [ ] Notion           api.notion.com
  [x] Slack            api.slack.com, slack.com
  [ ] Stripe           api.stripe.com
  -- Backend-only Twins --
  [ ] Box              api.box.com
  [ ] Jira             *.atlassian.net
  [ ] Unified          api.unified.to
  [ ] Unstructured     api.unstructuredapp.io
UI twins have an interactive dashboard you can open in the browser to see messages, files, and other state. Backend-only twins respond to API calls but don’t have a visual UI.
3

Review .env changes

The wizard scans your project for .env files and detects environment variables that match your selected twins.
Detected changes for .env:
  SLACK_BOT_TOKEN=          ->  xoxb-F9SXMECOSFOGYR3XKXWN
  UNSTRUCTURED_API_KEY=     ->  test-unstructured-key
  DROPBOX_APP_KEY=y4pd...   ->  dropbox-twin-app-key

? Apply these changes? (Y/n)
A backup is saved as .env.arga-backup before any changes are written.
4

Wait for provisioning

The wizard spins up ephemeral twin instances. This typically takes under a minute thanks to pre-warmed VMs.
Provisioning twin instances...

  [1/2] Discord twin .......... ready
  [2/2] Slack twin   .......... ready

  Session expires in 10 minutes.
5

Start building

The wizard prints a summary with everything you need:
┌──────────────────────────────┐
│  Arga Twins — Ready!                           │
│                                                │
│  Dashboard: https://app.argalabs.com/runs/...  │
│                                                │
│  Discord:  https://...--discord.sandbox....    │
│  Slack:    https://...--slack.sandbox....      │
│                                                │
│  Session expires: 2026-03-28T14:00:00Z         │
│                                                │
│  Commands:                                     │
│    arga-wizard status    Check health          │
│    arga-wizard reset     Reset twin state      │
│    arga-wizard extend    Extend by 10 min      │
│    arga-wizard teardown  Destroy session       │
└──────────────────────────────┘
Start your app normally — all API calls to the selected services are now routed through twins.

​
What the wizard does

Under the hood, the wizard:
  1. Validates your API key against the Arga API (or reads it from ~/.config/arga/config.json if you’ve run arga login)
  2. Provisions twin containers on Arga’s infrastructure via POST /validate/twins/provision
  3. Rewrites your .env to replace real API tokens with twin-compatible defaults
  4. Creates minimal auth infrastructure (tokens, bot users, root folders) so twins are ready to accept API calls — content is populated through scenario seeding
  5. Writes a .arga-session.json file that tracks the session for subsequent commands

​
Available twins

Type: UI twin (interactive dashboard)Intercepts: discord.com, api.discord.com, discordapp.comQuickstart state:
  • Server: “Default Server”
  • Users: twin-bot (bot)
  • Bot token: fake-bot-token
  • Channels, roles, members, and messages start empty — populate them through scenario seeding or API calls
File uploads: The Create Message endpoint accepts multipart/form-data requests with file attachments. Send files as files[n] or file form parts alongside a payload_json field (or a plain content field) and the twin records each upload as an attachment on the created message.
Type: UI twin (interactive dashboard)Intercepts: api.slack.com, slack.com, files.slack.comQuickstart state:
  • Workspace: “Default Workspace”
  • Users: slack-twin-bot (bot), slack-twin-user (human)
  • Bot token: xoxb-F9SXMECOSFOGYR3XKXWN
  • User token: xoxp-slack-twin-user-token
  • OAuth client ID: slack-twin-client-id
  • OAuth client secret: slack-twin-client-secret
  • Default tier: free (1 GB max file upload, same as pro, business_plus, enterprise, and paid tiers; see the admin API for tier details)
  • Channels start empty — populate them through scenario seeding or the conversations.create API
OAuth support: The Slack twin implements the OAuth 2.0 authorization code grant flow. Point your app’s Slack OAuth URLs at the twin (via SLACK_TWIN_BASE_URL) to test “Add to Slack” install flows without hitting real Slack servers. The twin issues working xoxb-, xoxp-, and xoxe.-prefixed tokens that can be used for subsequent API calls.Scope enforcement: The twin enforces OAuth scope requirements on every authenticated API call. If a token lacks the required scope for a method, the twin returns a missing_scope error — matching real Slack behavior. You can configure the scopes granted to bot and user tokens via scenario seeding to test permission edge cases.Tier limits: File uploads are subject to tier-based size limits. The twin starts on the free tier (1 GB cap — the same as paid tiers). Use the admin API to switch tiers (pro, business_plus, enterprise, or paid) to test tier-specific behavior. Each tier also controls message history limits, app install limits, and workflow availability.Workspace constraints: The twin supports workspace-level controls for disabling file uploads, enforcing storage quotas, and simulating rate limits. Configure these via scenario seeding or the admin API to test how your app handles restricted workspaces.Multi-sender UI: The inspector dashboard lets you post messages and add reactions as any user in the workspace via a sender picker, so you can test multi-user conversation flows without switching tokens manually.
Type: UI twin (interactive dashboard)Intercepts: www.googleapis.com/drive/v3, content.googleapis.comQuickstart state:
  • Principals: Drive Twin Owner, Drive Twin Editor
  • Owner token: ya29.drive-twin-owner
  • Files and folders start empty — populate them through scenario seeding or API calls
Type: UI twin (interactive dashboard)Intercepts: api.dropboxapi.com, content.dropboxapi.comQuickstart state:
  • Root folder initialized — files and folders start empty
  • Populate content through scenario seeding or API calls
Type: UI twin (interactive dashboard)Intercepts: api.github.com, github.comQuickstart state:
  • Token: ghp_test-github-twin-token
  • Users, organizations, and repositories start empty — populate them through scenario seeding or API calls
Supported resources: Repositories, pull requests (with merge and reviewer requests), issues, branches (with protection rules), commits, check runs, check suites, git references, labels, pull request reviews, commit statuses, file contents (branch-aware), search, organizations, users, GitHub App endpoints (installations, access tokens), webhooks, and OAuth flows.Scope enforcement: The twin enforces OAuth scope requirements on API calls. Each route requires a specific scope (for example, repo for repository operations, read:user for user info). Parent scopes grant their children automatically — repo implies repo:status, public_repo, etc. Configure default token scopes via default_token_scopes and disable specific scopes via disabled_scopes. See authentication handling for details.
Type: UI twin (interactive dashboard)Intercepts: api.notion.com, notion.soQuickstart state:
  • Workspace: “Notion Twin Workspace”
  • API key: secret_notion-twin_seed
  • Pages, databases, and users start empty — populate them through scenario seeding or API calls
Type: UI twin (interactive checkout pages)Intercepts: api.stripe.com, files.stripe.com, connect.stripe.comQuickstart state:
  • All Stripe API v1 resources start empty (no seeded data by default)
  • Use the /_twin/seed endpoint to create a starter product, price, and webhook endpoint
  • API key prefix: sk_test_ (any key with a valid prefix is accepted)
Supported resources: Customers, payment methods, payment intents, setup intents, charges, refunds, disputes, subscriptions, invoices, invoice items, credit notes, products, prices, plans, coupons, promotion codes, tax rates, shipping rates, tokens, sources, payouts, balance, billing meters, meter events, meter event summaries, events, files, file links, checkout sessions, payment links, quotes, billing portal, subscription items, subscription schedules, usage records, tax IDs, webhook endpoints, mandates, and test clocks.Browser pages: The twin serves browser-facing pages for checkout, billing portal, a multi-page dashboard (/dashboard with home, payments, subscriptions, invoices, and balances pages), product catalog (/products), and customer management (/customers). Use these to inspect twin state visually during a run — the dashboard home shows revenue, MRR, active subscribers, and recent payments; the products page shows all products and their prices; the customers page shows customers with their subscriptions. You can also test end-to-end payment flows including success, card decline, and 3D Secure scenarios through the checkout pages.Test cards: Stripe-compatible test card numbers trigger specific outcomes (declines, 3D Secure challenges, processing errors) — matching the behavior of Stripe’s own test mode.Webhook delivery: Register webhook endpoints via the API and the twin delivers signed events (Stripe-Signature header) to your application, just like the real Stripe.
Type: Backend-onlyIntercepts: api.box.com, upload.box.com, app.box.comQuickstart state:
  • Enterprise: “Box Twin Enterprise” (ID: 11446498)
  • Client ID: box-twin-client-id
  • Client Secret: box-twin-client-secret
  • Developer token: box-developer-token
  • Root folder and admin user created — files, sub-folders, and additional users start empty
Type: UI twin (interactive dashboard)Intercepts: www.googleapis.com/calendar/v3Calendar v3 API emulator with event CRUD operations. Calendars and events start empty — populate them through scenario seeding or API calls.
Type: Backend-onlyIntercepts: *.atlassian.net (Jira Cloud REST API v3)Quickstart state:
  • Cloud site: test-site.atlassian.net (cloud ID 11223344-a1b2-3b33-c444-def123456789)
  • OAuth client ID: jira-twin-client-id
  • OAuth client secret: jira-twin-client-secret
  • Webhook signing secret: test-jira-webhook-secret
  • Seeded metadata: priorities (Highest, High, Medium, Low, Lowest), statuses (To Do, In Progress, Done), issue types (Task, Bug, Story, Epic, Subtask), transitions, resolutions, and link types
  • Projects, issues, comments, worklogs, attachments, components, versions, filters, dashboards, groups, sprints, and boards start empty — populate them through scenario seeding or API calls
Supported resources: Issues (CRUD, bulk create, transitions, changelog, edit metadata, create metadata), projects, comments, worklogs, attachments, issue links, issue properties, votes, watchers, search and JQL search, users (myself, search, bulk, assignable, view-issue), components, versions, remote links, filters, dashboards, groups (and group members), fields, priorities, resolutions, statuses, status categories, issue types, server info, webhooks, and Agile endpoints (/rest/agile/1.0/ boards, sprints, backlog).API versioning: Routes registered under /rest/api/3/ are also reachable via the /rest/api/2/ and /rest/api/latest/ aliases, matching the real Jira Cloud REST API behavior.ADF content: Comments and issue descriptions are stored as Atlassian Document Format. Plain strings on input are auto-wrapped in a minimal ADF document so existing SDK calls continue to work.OAuth and scope enforcement: The twin implements the OAuth 2.0 authorization code grant flow at /authorize and /oauth/token. Every authenticated API call requires a Bearer token and is checked against the route’s required scope. See authentication handling for details on default token scopes (read:jira-work, write:jira-work, read:jira-user, manage:jira-project, manage:jira-webhook, manage:jira-configuration), parent-child scope expansion, and disabling scopes for testing.Webhook delivery: Register webhook endpoints via POST /rest/api/3/webhook and the twin delivers signed events for issue and comment changes.Admin endpoints: GET /admin/state, POST /admin/reset, POST /admin/clock (advance the twin’s clock by seconds), GET /admin/stub-hits, and POST /admin/stub-hits/clear.
Type: Backend-onlyIntercepts: api.unified.to, unified.toCreates Unified.to integration connections that proxy to Slack, Google Mail, Google Drive, Google Calendar, Box, Notion, and Dropbox. Use this twin only when your app talks to Unified.to directly. For actual provider data (channels, files, pages, repos, etc.), use the provider-specific twin instead.
Type: Backend-onlyIntercepts: api.unstructuredapp.io, platform.unstructuredapp.ioQuickstart state:
  • Partition endpoint ready at /general/v0/general
  • Jobs endpoint ready at /api/v1/jobs/
  • API key: test-unstructured-key
  • Workflow templates start empty — populate them through scenario seeding

​
Environment variables

The wizard recognizes these environment variables per twin and replaces them with twin-compatible defaults:
TwinVariables the wizard detects
DiscordDISCORD_TOKEN, DISCORD_BOT_TOKEN
SlackSLACK_BOT_TOKEN, SLACK_TOKEN, SLACK_SIGNING_SECRET, SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_TWIN_BASE_URL
StripeSTRIPE_SECRET_KEY, STRIPE_API_KEY, STRIPE_TWIN_BASE_URL, STRIPE_TWIN_WEBHOOK_SECRET
Google DriveGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_ACCESS_TOKEN
DropboxDROPBOX_APP_KEY, DROPBOX_APP_SECRET, DROPBOX_ACCESS_TOKEN
NotionNOTION_API_KEY, NOTION_TOKEN
BoxBOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_DEVELOPER_TOKEN
Google CalendarGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
JiraJIRA_BASE_URL, JIRA_HOST, JIRA_CLIENT_ID, JIRA_CLIENT_SECRET, JIRA_API_TOKEN
UnstructuredUNSTRUCTURED_API_KEY
UnifiedUNIFIED_API_KEY
Variables not associated with a selected twin are left untouched. The original file is always backed up to .env.arga-backup.

​
Session management

Twin sessions are ephemeral and expire after 10 minutes by default. Use these commands from your project directory: 
# Check if your twins are still running
arga wizard status     # or: npx arga-wizard status

# Reset all twins to their initial empty state
arga wizard reset      # or: npx arga-wizard reset

# Add another 10 minutes to the session
arga wizard extend     # or: npx arga-wizard extend

# Tear down immediately and clean up
arga wizard teardown   # or: npx arga-wizard teardown
Session state is stored in .arga-session.json in your project root. Add it to your .gitignore.

​
Inspect twin session logs

If twin provisioning stalls or something in the sandbox environment behaves unexpectedly, inspect the run logs from your project directory: 
arga runs logs
arga runs logs --errors-only
arga runs logs --json
Because the wizard writes .arga-session.json, arga runs logs can resolve the active run automatically from that directory. These logs are mostly about the twin/sandbox environment rather than your app’s own application logs. They include worker logs for build, deploy, and warm-up jobs plus runtime logs from the services Arga uses to provision and route the sandbox. Use --errors-only when you want a faster view of failed worker jobs and warning/error runtime entries. For the full CLI reference and response shape, see CLI and Get run logs.

​
Re-run just the .env step

If you need to update your .env without re-provisioning: 
arga-wizard env
This re-runs twin selection and .env rewriting without spinning up new instances.

​
Restoring your original .env

To revert to your original environment variables: 
cp .env.arga-backup .env

​
Next steps

Digital twins

Learn how twins intercept API calls and maintain state.

CLI

Full CLI reference including authentication and validation commands.

MCP

Install Arga context tools into your IDE agent.