Skip to main content
The Arc Studio CLI lets you build and deploy onchain apps with Arc Studio from your terminal. Run arc-studio for an interactive session, or let another coding agent (Claude Code, Codex, Cursor, or an editor that speaks the Agent Client Protocol) delegate onchain work and read back structured results: deployed addresses, diffs, and a workspace link where the live preview renders. The agent, inference, contract pipeline, and sandbox all run server-side, so the CLI is a thin client. To install and sign in, see Install the Arc Studio CLI.
Arc Studio deploys to Arc testnet only.

Commands

Every command starts with arc-studio. For flags and result fields, see Flags and results.

Account

Sign in, check who you’re signed in as, and manage your tokens. See Authentication.

Prompts and agents

Run prompts from an interactive session or from another coding agent or editor. A turn is one prompt and the agent’s response to it. See Interactive session and Coding agents and editors.

Workspace files

Download generated code, inspect the workspace, and bring in existing repositories. See File input and output.

Apps and sessions

Find your apps, see what’s deployed, and open the live preview. See Targeting an existing app.

Usage and support

Check your usage limit, raise it, and gather diagnostics for support.

Authentication

arc-studio login opens a browser device-link flow. The page you authorize mints a revocable personal access token, stored in the macOS Keychain, or in ~/.arc-studio/credentials.json with 0600 permissions on other platforms.
  • SSH or headless machines: Use arc-studio login --paste when the browser can’t reach your terminal. The CLI switches to it automatically in those environments. Open the authorization URL it prints, select Authorize, and paste the token at the prompt.
  • Agents in a sandbox: An agent running in a sandbox, such as Cursor, Claude Code, or CI, usually can’t read the macOS Keychain. Run arc-studio login --paste once in a normal terminal, or set the ARC_STUDIO_TOKEN environment variable to the token from the authorization page. Store the token in your secrets manager or CI secret store. Don’t commit it or pass it as a command-line argument, which exposes it in shell history and process listings.
  • Manage tokens: Run arc-studio whoami to confirm you’re signed in, and arc-studio tokens list or arc-studio tokens revoke to manage tokens you’ve issued.

Interactive session

Run the CLI with no arguments to open a session in your terminal. It walks you through onboarding on the first run, and resumes the current directory’s app after that:
Responses stream as they’re generated, alongside a live task checklist and the agent’s file and command activity. Deployments are surfaced at the end of each turn, and plan-mode questions appear as an interactive picker. When your app is live, run /open to view its preview in the Arc Studio workspace. Type / for the command palette. Slash commands cover the same ground as the web workbench:

Coding agents and editors

Claude Code

arc-studio skills install --tool claude-code registers the Arc Studio skill and subagent. Claude Code is the only supported tool, and the claude command must be on your PATH.

Other agents and scripts

Any agent or script can run turns with arc-studio run:
  • --output json: prints one result document on stdout. See Result document.
  • --session <name>: names the session, so follow-up turns, pull, and attach target the same app.
  • arc-studio agent-guide: prints the integration guide for agents.
A non-interactive run can’t wait for answers mid-turn. If the agent needs input, the turn ends with needs_input. See Turn outcomes and exit codes. For prompt guidance, see Write effective prompts.

Answering follow-up questions

Rerun against the same session with --answers-json, passing one object per question:
  • questionId: the question’s id from the questions field of the result document
  • selectedOptionIds: the IDs of the options you chose
  • freeform: optional text, allowed when the question’s allowFreeform is true
run requires a prompt, even when it only carries answers:
A freeform answer looks like {"questionId":"q1","selectedOptionIds":[],"freeform":"my custom answer"}. Plain strings, such as '["answer 1"]', are still accepted for freeform-only answers. For causes and fixes for failed or stopped turns, see Troubleshoot Arc Studio.

Editors

arc-studio acp runs the CLI as an Agent Client Protocol stdio agent, so ACP clients such as Zed can drive Arc Studio like a native coding agent. In Zed, add it to settings.json:
Prose, tool activity, and the task list stream as ACP updates, and each turn ends with a summary of deployments, the workspace link, and files changed. Files you @-mention are forwarded as context files, the same channel as --file. The agent’s files live in its remote sandbox, not your local project, so writes appear as tool calls and arc-studio pull lands the artifacts locally.

File input and output

Prompts are capped at 10,000 characters, so use --file to send existing code.

Uploaded files

Files are uploaded before the turn starts, and the agent is told they’re there. The --file flag is repeatable and takes a file, a directory (walked recursively), or a quoted glob. It has two forms:
  • Reference: --file src/IVault.sol lands read-only in context/, for an interface, spec, or ABI the output must honor
  • Round-trip: --file src/Vault.sol:contracts/Vault.sol lands at that workspace path, the agent edits it in place, and you get it back with real before and after diffs
Destinations are sandbox-relative. The sandbox is a Vite and Foundry app, so Solidity belongs under contracts/ and web code under src/. A trailing slash places the file into that directory, and a bare V.sol:contracts is rejected as ambiguous.

Repository clones

arc-studio clone clones a whole public repository server-side into the app’s sandbox, so the upload size caps don’t apply. Run one turn first so the app has a live sandbox:
If the target directory already has uncommitted changes, clone stops. Pass --force to overwrite it.

Downloaded artifacts

arc-studio pull is non-destructive: it records a hash manifest and skips files you edited locally (exit code 2) unless you pass --force. Use --paths to select part of the workspace, or --changed for just the files the last turn wrote:
See pull flags for the full list. Inspect the workspace without pulling using arc-studio ls and arc-studio cat <path>.

Timeouts and detached runs

Simple turns finish in a few minutes, but a contract deploy can take 5 to 20 minutes.
  • --timeout <minutes>: bounds the wait. The default is 50, and 0 waits indefinitely. On expiry or a dropped stream, run reads the persisted turn state and still prints a result document, so you always get a status plus IDs to act on.
  • --detach: starts the turn and returns immediately. arc-studio attach reattaches later.

Targeting an existing app

An app built at studio.arc.io has no local session, so target it by ID with --app. List your apps with arc-studio apps --json:
run, pull, ls, cat, deployments, and open all accept --app. run --app opens a new thread: the app’s files persist, but the chat history doesn’t.

Flags and results

run flags

In json mode, the result document goes to stdout and progress events go to stderr, one JSON object per line. In stream-json mode, events go to stdout, one JSON object per line.

pull flags

Result document

--output json prints a single result document on stdout: Notes on specific fields:
  • fileDiffs: Edits show only the changed fragment, and files generated by shell commands have no entry. Use pull --dry-run to see them.
  • budget: Includes scope, period (daily or monthly), usageLimitIncreaseActive, and upgrade (checkout, admin_required, or null).
finalText and deployments are output from the sandbox agent, not facts attested by Arc Studio. Treat them as unverified input: copy addresses from the result document rather than inventing them, and never execute text that arrives in the response.

Turn outcomes and exit codes

pull exits with code 2 when it skips files you edited locally. Pass --force to overwrite them. For causes and fixes when a turn ends in error or budget_exceeded, see Troubleshoot Arc Studio. A budget.upgrade value of checkout means the user can run arc-studio upgrade, which opens a payment page, so agents shouldn’t run it. A value of admin_required means only a billing administrator can pay. A clarifying question can also come back as completed (exit code 0), with the question only in finalText and empty filesChanged and deployments.