Usar con agentes

CLI

La CLI tiene los mismos comandos que el MCP, con nombres en kebab-case. Sirve para scripts, integración continua y servidores sin interfaz gráfica.

Cómo obtenerla

Dónde	Cómo se ejecuta
Imagen Docker	`canvappen <comando>` dentro del contenedor. Ver Imagen Docker
Código fuente	`pnpm cli <comando>` desde el repositorio, después de `pnpm install` y `pnpm build`

Uso

CLI

canvappen <comando> [opciones]
canvappen help <comando|tema>
canvappen <comando> --help

Opción global	Efecto
`--json`	Respuesta en JSON, para procesarla en scripts
`--help`	Ayuda del comando
`--version`	Versión de canvappen

Código de salida	Significado
`0`	Correcto
`1`	Error en la operación o archivo inválido
`2`	Uso incorrecto: comando u opción desconocidos, o falta un argumento

Comandos

Referencia

`inspect`

Resumen del documentoSolo lectura

Devuelve la versión, la cantidad de nodos, los frames raíz con posición y tamaño, las variables, los themes, las librerías importadas y los componentes locales. Indica si el documento está abierto en la app canvappen.

Uso

canvappen inspect <path>

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)

Ejemplos

Resumen de un diseño

CLI

canvappen inspect design.pen

RespuestaJSON con path, openInApp, version, nodeCount, roots, themes, variables, imports y components

`get-nodes`

Leer nodosSolo lectura

Devuelve nodos por id con sus hijos hasta 'depth'. Con resolve expande instancias (ref) y variables y agrega 'bounds' calculados (posición absoluta y tamaño). Sin ids devuelve los nodos raíz.

Uso

canvappen get-nodes <path> [--ids <ids>] [--depth <depth>] [--resolve]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--ids`	lista de textos	Ids de nodos; para descendientes de instancias usa 'instancia/descendiente'
`--depth`	entero	Profundidad de hijosde 0 a 20 · por defecto 2
`--resolve`	sí/no	Expandir instancias y variables y calcular boundspor defecto false

Ejemplos

Leer un frame con dos niveles

CLI

canvappen get-nodes design.pen --ids Lg3Bf

Con posición calculada

CLI

canvappen get-nodes design.pen --ids Lg3Bf --resolve

RespuestaJSON: lista de nodos

`search-nodes`

Buscar nodosSolo lectura

Busca nodos por nombre, contenido de texto o tipo. Devuelve id, tipo, nombre, ancestros y un fragmento del texto.

Uso

canvappen search-nodes <path> [--query <query>] [--type <type>] [--reusable-only] [--limit <limit>]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--query`	texto	Texto a buscar en name y content, sin distinguir mayúsculas
`--type`	texto	Filtrar por tipo de nodo (frame, text, ref…)
`--reusable-only`	sí/no	Solo componentes (reusable)por defecto false
`--limit`	entero	Máximo de resultadosde 1 a 500 · por defecto 50

Ejemplos

Buscar botones

CLI

canvappen search-nodes design.pen --query botón

RespuestaJSON con count y results

`list-components`

Listar componentesSolo lectura

Lista los componentes (reusable) del documento y de las librerías .lib.pen importadas, con el id que debe usarse en 'ref'.

Uso

canvappen list-components <path>

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)

Ejemplos

Componentes disponibles

CLI

canvappen list-components design.pen

RespuestaJSON con libraries, count y components

`get-variables`

Variables y themesSolo lectura

Devuelve las variables (definición y valor resuelto) y los ejes de theme. Opcionalmente resuelve con una selección de theme.

Uso

canvappen get-variables <path> [--theme <theme>]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--theme`	objeto	Selección de theme, por ejemplo {"mode":"dark"} (en la CLI: --theme mode=dark)

Ejemplos

Variables en modo oscuro

CLI

canvappen get-variables design.pen --theme mode=dark

RespuestaJSON con themes, theme y variables

`validate`

ValidarSolo lectura

Valida el documento contra el schema 2.21 y reporta migraciones necesarias, normalizaciones y errores.

Uso

canvappen validate <path...>

Parámetros

Parámetro	Tipo	Descripción
`<path...>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)

Ejemplos

Validar un diseño

CLI

canvappen validate design.pen

Validar varios

CLI

canvappen validate *.pen

RespuestaJSON con valid, migratedFrom, warnings e issues. En la CLI el código de salida es 1 si algún archivo tiene errores

`migrate`

MigrarCrea archivosSolo CLI

Muestra qué cambiaría al migrar a 2.21; con write escribe el archivo. El MCP no lo necesita porque siempre guarda en 2.21.

Uso

canvappen migrate <path...> [--write]

Parámetros

Parámetro	Tipo	Descripción
`<path...>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--write`	sí/no	Escribir el archivo (escritura atómica)por defecto false

Ejemplos

Migrar todos los diseños

CLI

canvappen migrate *.pen --write

RespuestaUn resultado por archivo

`format`

FormatearCrea archivosSolo CLI

Muestra qué cambiaría al reescribir en el formato canónico (orden de claves e indentación); con write escribe el archivo.

Uso

canvappen format <path...> [--write]

Parámetros

Parámetro	Tipo	Descripción
`<path...>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--write`	sí/no	Escribir el archivo (escritura atómica)por defecto false

Ejemplos

Formatear un diseño

CLI

canvappen format design.pen --write

RespuestaUn resultado por archivo

`apply-operations`

Aplicar operacionesModifica el archivo

Aplica operaciones de edición en una transacción: insert, update, delete, move, replace, copy, detach, set_variables, set_themes, set_imports y set_fonts (ver el tema operations). Si la app canvappen tiene el documento abierto, el cambio se ve en vivo con el puntero del agente; si no, se escribe el archivo con respaldo. Si el archivo no existe, se crea.

Uso

canvappen apply-operations <path> --operations <operations> [--dry-run] [--label <label>]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--operations`obligatorio	JSON	Lista de operaciones (en la CLI: archivo .json, '-' para stdin o JSON en línea)
`--dry-run`	sí/no	Valida y simula sin guardarpor defecto false
`--label`	texto	Descripción corta del cambio (se muestra en la app)

Ejemplos

Cambiar un texto

CLI

canvappen apply-operations design.pen --operations cambios.json

Separar una instancia

CLI

echo '[{"op":"detach","id":"card1"}]' | canvappen apply-operations design.pen --operations -

RespuestaJSON con appliedIn, createdIds, affectedIds, deletedIds y backup

`convert-to-library`

Convertir en libreríaModifica el archivo

Renombra el archivo a .lib.pen para usarlo como librería de componentes. Solo es posible si el documento no tiene librerías adjuntas. Si el documento está abierto en la app, ciérralo antes.

Uso

canvappen convert-to-library <path>

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)

Ejemplos

Convertir un sistema de diseño

CLI

canvappen convert-to-library sistema.pen

RespuestaJSON con from y to

`import-image`

Importar imagenCrea archivos

Copia una imagen local (.png, .jpg, .jpeg, .webp o .gif) a la carpeta images/ del documento (sin duplicar si el contenido es igual) y, si insert es verdadero, inserta un rectángulo con la imagen a su tamaño real (máximo 1200 px).

Uso

canvappen import-image <path> --source <source> [--insert] [--parent <parent>] [--x <x>] [--y <y>] [--name <name>]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--source`obligatorio	texto	Ruta de la imagen a importar
`--insert`	sí/no	Insertar un nodo con la imagenpor defecto true
`--parent`	texto	Id del frame donde insertar; por defecto en la raíz
`--x`	número	Posición X
`--y`	número	Posición Y
`--name`	texto	Nombre del nodo; por defecto el nombre del archivo

Ejemplos

Usar una foto de Descargas

CLI

canvappen import-image design.pen --source ~/Downloads/foto.jpg --parent hero

RespuestaJSON con url (relativa al .pen), width, height y nodeId

`import-font`

Importar fuenteCrea archivos

Copia la fuente a la carpeta fonts/ del documento, lee su familia, peso y estilo, y la agrega a 'fonts' del .pen.

Uso

canvappen import-font <path> --source <source>

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--source`obligatorio	texto	Ruta del archivo .ttf u .otf

Ejemplos

Agregar una fuente

CLI

canvappen import-font design.pen --source ~/Downloads/Marca-Bold.otf

RespuestaJSON con name, url, weight y style

`localize`

Hacer autocontenidoCrea archivos

Descarga a la carpeta del documento las fuentes que hoy vienen de Google Fonts (solo los pesos y estilos que se usan, incluidos los de componentes de librerías) y las imágenes por http(s), y cambia las referencias del .pen a esos archivos. Después el documento se renderiza y exporta sin internet. Solo descarga de dominios permitidos: allowedHosts de la configuración o los permitidos por una persona para ese documento. Las fuentes del sistema que no están en Google Fonts se informan para importarlas con import_font.

Uso

canvappen localize <path> [--with-libraries]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--with-libraries`	sí/no	También localizar las librerías .lib.pen importadas (modifica esos archivos)por defecto false

Ejemplos

Preparar una presentación para el servidor

CLI

canvappen localize deck.pen

Incluir las librerías

CLI

canvappen localize deck.pen --with-libraries

RespuestaJSON con files (por archivo: fuentes, imágenes y recursos omitidos con el motivo) y complete. En la CLI el código de salida es 1 si quedó algún recurso sin localizar

`permissions`

Permisos de redCrea archivosSolo CLI

Lista, permite, bloquea o reinicia los permisos de dominios remotos de un documento. No está en el MCP: un agente no debe poder darse permisos de red.

Uso

canvappen permissions <path> [--allow <allow>] [--deny <deny>] [--reset <reset>]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--allow`	lista de textos	Dominios a permitir
`--deny`	lista de textos	Dominios a bloquear
`--reset`	lista de textos	Dominios a reiniciar

Ejemplos

Permitir Google Fonts

CLI

canvappen permissions design.pen --allow fonts.googleapis.com --allow fonts.gstatic.com

RespuestaJSON con los permisos del documento

`export`

ExportarCrea archivos

Exporta nodos o el documento completo. Con ids se respeta su orden; sin ids se exporta todo en orden de lectura del canvas. Por defecto guarda en <carpeta del .pen>/exports/<nombre-del-pen>/ (ver el tema export).

Uso

canvappen export <path> --format <format> [--ids <ids>] [--scale <scale>] [--quality <quality>] [--out <out>] [--overwrite] [--strict]

Parámetros

Parámetro	Tipo	Descripción
`<path>`obligatorio	texto	Ruta del archivo .pen (absoluta, relativa o con ~)
`--format`obligatorio	`pdf` `svg` `png` `jpeg` `webp` `html`	Formato de salida
`--ids`	lista de textos	Ids de nodos; para descendientes de instancias usa 'instancia/descendiente'
`--scale`	número	Escala (no aplica a SVG ni HTML)de 1 a 4 · por defecto 2
`--quality`	`high` `medium` `low`	Calidad (no aplica a SVG ni HTML)por defecto "high"
`--out`	texto	Ruta de salida; por defecto exports/<nombre-del-pen>/
`--overwrite`	sí/no	Sobrescribir si out ya existe (dentro de exports/ siempre se sobrescribe)por defecto false
`--strict`	sí/no	Fallar si falta alguna fuente, imagen, icono, componente de librería o hay errores de scripts (por defecto, según la configuración: "strict" en config.json o CANVAPPEN_STRICT)

Ejemplos

Presentación completa en PDF

CLI

canvappen export deck.pen --format pdf

Tres láminas en un orden propio

CLI

canvappen export deck.pen --format pdf --ids c3,a1,b2

Un frame en PNG a 3x

CLI

canvappen export design.pen --format png --ids Lg3Bf --scale 3

RespuestaJSON con file, kind, count, order, bytes y siempre missingFonts, missingImages, missingIcons, brokenLibraries y scriptErrors (aunque estén vacíos). Con strict y algún faltante no se escribe el archivo y la respuesta es un error (código 1 en la CLI)

`help`

AyudaSolo lectura

Sin topic devuelve la vista general: qué es canvappen, el catálogo de funcionalidades y la lista de temas. Con topic devuelve el detalle de una funcionalidad (parámetros, respuesta y ejemplos) o de un tema: pen-format, operations, export o files.

Uso

canvappen help [topic]

Parámetros

Parámetro	Tipo	Descripción
`<topic>`	texto	Funcionalidad o tema (por ejemplo export, pen-format u operations)

Ejemplos

Vista general

CLI

canvappen help

Detalle de la exportación

CLI

canvappen help export

Formato .pen

CLI

canvappen help pen-format

RespuestaTexto en Markdown

CLI

Cómo obtenerla

Uso

Comandos

Leer el documento

Revisar y mantener

Editar

Imágenes, fuentes y recursos

Exportar

Ayuda

Referencia

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos

Parámetros

Ejemplos