The arclip CLI

arclip puts a project in a terminal. An agent you already use — Claude Code, Codex, Cursor — builds the scene with the same tools as the editor's assistant, and checks its own work before it tells you it is done. Scripts and CI use the same commands.

Every command is one call to the MCP server, so the CLI can do nothing the editor's tools cannot, and never drifts from them.

Install

npm i -g arclip

It needs Node 18 or newer. arclip render --real also needs Node 22 and Google Chrome or Chromium on the machine.

Quick start

arclip login                  # sign in once, in the browser
arclip link <project-id>      # in your folder: set it up for agents
arclip dev                    # a QR code — the live draft on your phone
claude                        # or codex, or Cursor — ask for the scene
arclip verify && arclip render -o shot.png
arclip publish                # when you are happy

arclip projects lists the projects you can open. The id is also the last part of the editor address: editor.arclip.design/project/<project-id>.

Signing in

arclip login opens your browser on the same permission page an MCP client gets. Untick what you do not want to grant, press Allow, and the CLI receives a token. arclip login --token arclip_… stores a token you created yourself instead; --no-browser only prints the address, for you to open in a browser on the same machine.

The token is kept in your user config (~/.config/arclip), readable only by you, and is only ever sent to the server that issued it. arclip whoami shows the account, server and permissions in use; arclip logout forgets the token. You can revoke it at any time in your account, under API & MCP.

What arclip link sets up

Run it in any folder — a new one, or your existing repository:

File	What it is for
.arclip/project.json	which project this folder belongs to — safe to commit
CLAUDE.md	the agent's routine: build, verify, render, playtest, report — and never publish unasked
.mcp.json	the AR Clip MCP server, started through the CLI and pinned to this project; no token inside
.claude/settings.json	lets the agent read these docs and run the read-only checks without asking; publishing asks

Files you already have are merged, not overwritten; an existing CLAUDE.md is kept unless you pass --force.

arclip clone <project-id> [folder] does the same in a new folder, and brings the project's scripts and UI cards down as files.

Scripts and UI cards as files

arclip pull        # server → folder: scripts/**/*.ts and ui/**/*.json
arclip diff        # what you changed, line by line
arclip push        # folder → server

push compiles every script first, and sends nothing if the project changed on the server since your last pull — pull, look at the difference, then push again (--force overwrites). New files are created on the server; deleting a file locally does not delete it there. pull leaves alone a file that changed on both sides and tells you about it.

The scene itself — objects, components, events — stays on the platform, where people edit it together; it is not pulled as files.

Your scene on your phone

arclip dev

prints a link and a QR code. Scan it and the draft opens in the phone's browser — no sign-in, no publishing. The terminal keeps running: every edit, from the agent or from a colleague in the editor, is reported and the scene re-checked, and the phone offers the new version. A running AR session offers to reload instead of swapping the scene under you.

arclip dev --watch also pushes scripts/ and ui/ as you save them. The link expires after --hours (12 by default, 72 at most).

The draft opens in the phone's browser, not in the AR Clip app.

Checking the work

Command	What it tells you
arclip verify	what saves fine and fails silently in the player — missing files, unknown events, a dark scene
arclip render	a PNG drawn on the server: layout, scale, colours, textures
arclip render --real	the published runtime in headless Chrome on your machine — exactly what a visitor sees
arclip playtest	runs the scripts and physics and presses every control it finds
arclip test	runs your scripted scenarios, tests/*.flow.json

Each of them exits with code 1 when something fails, so an agent — or CI — can stop on it.

render takes --view front|side|back|top|three-quarter, --entity <id> to frame one object, --size 960x720 and -o file.png. The server-side render does not draw scripts, UI cards or effects; --real does, for 3D and surface scenes. Scenes that start from a camera — markers, faces, VPS — need a device.

playtest and test play the scene in the editor, so the project has to be open in a browser tab.

Scripted tests (flows)

A flow is a scenario with expectations, one per file in tests/. arclip link adds a starter one.

{
  "name": "door opens",
  "steps": [
    { "frames": 30 },
    { "tap": "Door button" },
    { "wait": 500 },
    { "expect": { "target": "Door", "position": { "x": 1.2, "tolerance": 0.05 } } },
    { "key": "KeyW", "ms": 400 },
    { "expect": { "target": "Player", "moved": true } },
    { "ui": "HUD", "action": "restart" },
    { "expect": { "noCrashes": true } }
  ]
}

Step	Does
frames	advances that many ticks
wait	advances that many milliseconds
key + ms	holds a key, then releases it
tap	taps an object
ui + action	fires an action on a UI card
input + target, payload	sends any script trigger
expect	checks exists, visible, position, moved, a component field, or noCrashes

Targets are object names as the editor shows them, or ids. Each flow runs on a fresh copy of the scene, and time only moves in fixed 1/60 s steps — a flow that passes once passes every time.

arclip test runs them all; arclip test "door opens" runs one.

Publishing and hosting it yourself

arclip publish publishes and prints the link and a QR code; it asks first (--yes in CI). arclip status shows the scenes and the publication state; arclip open opens the published link.

arclip export site && arclip serve site

export writes one folder — index.html, the scene as project.json, every file it uses, the fonts and the player — that runs from any static host: your own server, S3, an intranet. Only the fallback glyphs for scripts the fonts lack (CJK, Arabic, …) still come from the AR Clip CDN. Assets from the shared library keep their licence terms.

Agents and other MCP clients

arclip mcp serve is a local bridge to the MCP server, pinned to the linked project — it is what .mcp.json starts. arclip mcp config prints that entry, for a client that keeps its own list.

Any tool is one command away:

arclip tools                                   # what this account can call
arclip call get_entity '{"entityId":"…"}'      # arguments as JSON, or "-" for stdin

Scripts and CI

• The result goes to stdout, diagnostics to stderr; --json makes every result machine-readable.
• Exit code 0 is success, 1 a failed check or tool, 2 a usage or sign-in problem.
• CI needs no login — put a token and a project in the environment:

export ARCLIP_TOKEN=arclip_…
export ARCLIP_PROJECT=<project-id>
arclip verify --json
arclip render --view top -o top.png

ARCLIP_API points the CLI at another server, like --api. -p, --project and --space choose the project and scene for one command.

Limits

• The scene lives on the platform; scripts and UI cards are the only parts you work on as files.
• playtest and test need the project open in an editor tab, including in CI.
• arclip render is a preview; use --real, or a device, when the exact look matters.
• What an agent may do follows your token's permissions and your plan. AI generation spends your team's credits, as it does in the editor.

---

Next: What agents are good for here