La CLI de arclip

arclip lleva un proyecto a la terminal. Un agente que ya usas —Claude Code, Codex, Cursor— construye la escena con las mismas herramientas que el asistente del editor, y comprueba su propio trabajo antes de decirte que ha terminado. Los scripts y la CI usan los mismos comandos.

Cada comando es una llamada al servidor MCP, así que la CLI no puede hacer nada que no hagan ya las herramientas del editor, y nunca se desvía de ellas.

Instalación

npm i -g arclip

Necesita Node 18 o posterior. arclip render --real necesita además Node 22 y Google Chrome o Chromium en la máquina.

Inicio rápido

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 lista los proyectos que puedes abrir. El id es también la última parte de la dirección del editor: editor.arclip.design/project/<project-id>.

Iniciar sesión

arclip login abre en tu navegador la misma página de permisos que recibe un cliente MCP. Desmarca lo que no quieras conceder, pulsa Allow y la CLI recibe un token. arclip login --token arclip_… guarda en su lugar un token que hayas creado tú; --no-browser solo imprime la dirección, para que la abras en un navegador de la misma máquina.

El token se guarda en tu configuración de usuario (~/.config/arclip), solo tú puedes leerlo, y únicamente se envía al servidor que lo emitió. arclip whoami muestra la cuenta, el servidor y los permisos en uso; arclip logout olvida el token. Puedes revocarlo en cualquier momento desde tu cuenta, en API & MCP.

Qué prepara arclip link

Ejecútalo en cualquier carpeta, ya sea una nueva o tu repositorio de siempre:

Archivo	Para qué sirve
.arclip/project.json	a qué proyecto pertenece esta carpeta; puedes incluirlo en el repositorio sin problema
CLAUDE.md	la rutina del agente: construir, verificar, renderizar, hacer playtest, informar, y no publicar nunca sin que se lo pidan
.mcp.json	el servidor MCP de AR Clip, arrancado a través de la CLI y fijado a este proyecto; sin token dentro
.claude/settings.json	deja que el agente lea esta documentación y ejecute las comprobaciones de solo lectura sin preguntar; para publicar, pregunta

Los archivos que ya tienes se fusionan, no se sobrescriben; un CLAUDE.md existente se conserva salvo que pases --force.

arclip clone <project-id> [folder] hace lo mismo en una carpeta nueva, y además se trae los scripts y las tarjetas de UI del proyecto como archivos.

Scripts y tarjetas de UI como archivos

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

push compila primero cada script, y no envía nada si el proyecto ha cambiado en el servidor desde tu último pull: haz pull, revisa la diferencia y vuelve a hacer push (--force sobrescribe). Los archivos nuevos se crean en el servidor; borrar un archivo en local no lo borra allí. pull no toca un archivo que ha cambiado en ambos lados, y te avisa.

La escena en sí —objetos, componentes, eventos— se queda en la plataforma, donde la gente la edita en conjunto; no se descarga como archivos.

Tu escena en tu móvil

arclip dev

imprime un enlace y un código QR. Escanéalo y el borrador se abre en el navegador del móvil: sin iniciar sesión y sin publicar. La terminal sigue en marcha: cada edición, venga del agente o de un compañero en el editor, se notifica y la escena se vuelve a comprobar, y el móvil ofrece la versión nueva. Si hay una sesión AR en curso, ofrece recargar en vez de cambiarte la escena mientras la estás usando.

arclip dev --watch además hace push de scripts/ y ui/ a medida que los guardas. El enlace caduca pasadas las --hours indicadas (12 por defecto, 72 como máximo).

El borrador se abre en el navegador del móvil, no en la app de AR Clip.

Comprobar el trabajo

Comando	Qué te dice
arclip verify	lo que se guarda sin problema y falla en silencio en el reproductor: archivos que faltan, eventos desconocidos, una escena a oscuras
arclip render	un PNG dibujado en el servidor: disposición, escala, colores, texturas
arclip render --real	el runtime publicado en Chrome headless en tu máquina: exactamente lo que ve un visitante
arclip playtest	ejecuta los scripts y la física y pulsa cada control que encuentra
arclip test	ejecuta tus escenarios guionizados, tests/*.flow.json

Todos terminan con código 1 cuando algo falla, así que un agente —o la CI— puede detenerse ahí.

render admite --view front|side|back|top|three-quarter, --entity <id> para encuadrar un objeto, --size 960x720 y -o file.png. El render del servidor no dibuja scripts, tarjetas de UI ni efectos; --real sí, para escenas 3D y Surface. Las escenas que arrancan desde una cámara —marcadores, caras, VPS— necesitan un dispositivo.

playtest y test reproducen la escena en el editor, así que el proyecto tiene que estar abierto en una pestaña del navegador.

Pruebas guionizadas (flujos)

Un flujo es un escenario con expectativas, uno por archivo en tests/. arclip link añade uno de partida.

{
  "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 } }
  ]
}

Paso	Hace
frames	avanza ese número de ticks
wait	avanza ese número de milisegundos
key + ms	mantiene pulsada una tecla y luego la suelta
tap	toca un objeto
ui + action	lanza una acción en una tarjeta de UI
input + target, payload	envía cualquier disparador de script
expect	comprueba exists, visible, position, moved, un campo de component o noCrashes

Los objetivos son nombres de objeto tal como los muestra el editor, o ids. Cada flujo se ejecuta sobre una copia nueva de la escena, y el tiempo solo avanza en pasos fijos de 1/60 s: un flujo que pasa una vez pasa siempre.

arclip test los ejecuta todos; arclip test "door opens" ejecuta uno.

Publicar y alojarlo tú mismo

arclip publish publica e imprime el enlace y un código QR; antes pregunta (--yes en CI). arclip status muestra las escenas y el estado de publicación; arclip open abre el enlace publicado.

arclip export site && arclip serve site

export escribe una sola carpeta —index.html, la escena como project.json, cada archivo que usa, las fuentes y el reproductor— que funciona desde cualquier hosting estático: tu propio servidor, S3, una intranet. Solo los glifos de reserva para los sistemas de escritura que no cubren las fuentes (CJK, árabe, …) siguen viniendo de la CDN de AR Clip. Los assets de la biblioteca compartida mantienen sus condiciones de licencia.

Agentes y otros clientes MCP

arclip mcp serve es un puente local al servidor MCP, fijado al proyecto vinculado: es lo que arranca .mcp.json. arclip mcp config imprime esa entrada, para un cliente que lleva su propia lista.

Cualquier herramienta está a un comando de distancia:

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

Scripts y CI

• El resultado va a stdout y los diagnósticos a stderr; --json hace que cada resultado sea legible por máquina.
• El código de salida 0 es éxito, 1 una comprobación o herramienta fallida, 2 un problema de uso o de inicio de sesión.
• La CI no necesita iniciar sesión: pon un token y un proyecto en el entorno:

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

ARCLIP_API apunta la CLI a otro servidor, igual que --api. -p, --project y --space eligen el proyecto y la escena para un solo comando.

Límites

• La escena vive en la plataforma; los scripts y las tarjetas de UI son las únicas partes con las que trabajas como archivos.
• playtest y test necesitan el proyecto abierto en una pestaña del editor, también en CI.
• arclip render es una vista previa; usa --real, o un dispositivo, cuando importe el aspecto exacto.
• Lo que puede hacer un agente depende de los permisos de tu token y de tu plan. La generación por IA gasta los créditos de tu equipo, igual que en el editor.

---

Siguiente: Para qué sirven aquí los agentes