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 witharc-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 --pastewhen 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 --pasteonce in a normal terminal, or set theARC_STUDIO_TOKENenvironment 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 whoamito confirm you’re signed in, andarc-studio tokens listorarc-studio tokens revoketo 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:/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 witharc-studio run:
--output json: prints one result document onstdout. See Result document.--session <name>: names the session, so follow-up turns,pull, andattachtarget the same app.arc-studio agent-guide: prints the integration guide for agents.
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’sidfrom thequestionsfield of the result documentselectedOptionIds: the IDs of the options you chosefreeform: optional text, allowed when the question’sallowFreeformistrue
run requires a prompt, even when it only carries answers:
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:
@-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.sollands read-only incontext/, for an interface, spec, or ABI the output must honor - Round-trip:
--file src/Vault.sol:contracts/Vault.sollands at that workspace path, the agent edits it in place, and you get it back with real before and after diffs
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:
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:
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, and0waits indefinitely. On expiry or a dropped stream,runreads 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 attachreattaches 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. Usepull --dry-runto see them.budget: Includesscope,period(dailyormonthly),usageLimitIncreaseActive, andupgrade(checkout,admin_required, ornull).
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.