Comandos del CLI - Faces Docs

`new`

Crea un nuevo proyecto en blanco. Devuelve el projectSlug y la editorUrl. Agrega diapositivas con faces slides create + faces slides update. El proyecto se crea bajo el equipo al que está asociada tu API key (consulta Autenticación).

faces new

Opciones:

Flag	Descripción
`--name <text>`	Nombre visible para el nuevo proyecto (por defecto: `Untitled`)
`--api-key <key>`	Sobrescribe la API key

Salida:

{
  "projectId": "cm1abc123...",
  "projectSlug": "xK9mP2qR",
  "projectVersionId": "cm1ver456...",
  "editorUrl": "https://faces.app/s/xK9mP2qR"
}

Ejemplos:

faces new
faces new --name "Q4 Roadmap"

`generate`

Genera una nueva presentación interactiva a partir de un prompt de texto. Describe lo que quieres (un pitch, portafolio, guía o propuesta) y Faces se encarga del contenido, las animaciones y el diseño.

faces generate --prompt "5-slide pitch deck about AI in healthcare"

Opciones:

Flag	Descripción
`--prompt <text>`	(requerido) Descripción del proyecto a generar
`--template <id>`	Usa un proyecto existente como plantilla
`--wait`	Espera a que el proyecto termine de generarse
`--api-key <key>`	Sobrescribe la API key

Salida:

{
  "jobId": "cm1abc123...",
  "status": "processing",
  "editorUrl": "https://faces.app/s/xK9mP2qR"
}

Ejemplos:

# Generación básica
faces generate --prompt "Company intro deck with 3 slides"

# Usando una plantilla
faces generate --prompt "Same deck for fintech" --template cm1xyz789

# Esperar a que termine
faces generate --prompt "Team intro" --wait

`status`

Verifica el estado de un job de generación.

faces status <job-id>

Opciones:

Flag	Descripción
`--wait`	Consulta hasta que el job termine o falle
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

# Verificar una vez
faces status cm1abc123...

# Esperar a que termine
faces status cm1abc123... --wait

`list`

Lista tus proyectos.

faces list

Opciones:

Flag	Descripción
`--published`	Mostrar solo proyectos publicados
`--limit <n>`	Máximo de resultados (por defecto: 20, máximo: 100)
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

faces list --published --limit 5
faces list | jq '.projects[].slug'

`get`

Obtiene los detalles de un proyecto específico.

faces get <slug>

Ejemplos:

faces get xK9mP2qR
faces get xK9mP2qR | jq '.publishedUrl'

`rename`

Renombra un proyecto. Cambia solo el nombre visible; el slug y las URLs permanecen iguales.

faces rename <slug> --name "New Name"

Opciones:

Flag	Descripción
`--name <text>`	(requerido) Nuevo nombre visible
`--api-key <key>`	Sobrescribe la API key

`duplicate`

Crea una copia completa de un proyecto, incluidas todas sus diapositivas. La copia obtiene su propio slug y una nueva URL sin publicar.

faces duplicate <slug>

Ejemplos:

faces duplicate xK9mP2qR
faces duplicate xK9mP2qR | jq -r '.editorUrl'

`publish`

Publica la última versión de un proyecto en su URL en vivo.

faces publish <slug>

Ejemplos:

faces publish xK9mP2qR
faces publish xK9mP2qR | jq -r '.publishedUrl'

`unpublish`

Retira de la web un proyecto publicado. El proyecto y sus diapositivas se conservan y se pueden volver a publicar más tarde.

faces unpublish <slug>

`config get`

Lee el project.config.json de un proyecto, incluidas sus opciones de diseño y los tokens de diseño compartidos (paleta y fuentes).

faces config get <slug>

Ejemplos:

faces config get xK9mP2qR
faces config get xK9mP2qR | jq '.tokens'

`config update`

Combina claves en project.config.json. Úsalo para definir los tokens de diseño del proyecto. Solo se modifican las claves que pasas; el resto se conserva.

faces config update <slug> --config <json-or-file>

Opciones:

Flag	Descripción
`--config <json-or-file>`	(requerido) Un objeto JSON o la ruta a un archivo JSON con las claves de configuración a combinar
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

faces config update xK9mP2qR --config ./tokens.json
faces config update xK9mP2qR --config '{"tokens":{"palette":[{"name":"--background","value":"#0D0D0D"}],"fonts":[]}}'

`url get`

Obtiene la configuración de URL actual de un proyecto más los subdominios y dominios disponibles para cambiar.

faces url get <slug>

Ejemplos:

faces url get xK9mP2qR
faces url get xK9mP2qR | jq '.availableSubdomains'

`url set`

Cambia la ruta, cambia de subdominio o apunta el proyecto a un dominio personalizado. Requiere un plan de pago.

faces url set <slug> --path <p> [--subdomain-id <id> | --domain-id <id>]

Opciones:

Flag	Descripción
`--path <p>`	(requerido) Segmento de ruta después del hostname (usa `""` para la raíz)
`--subdomain-id <id>`	Subdominio en el que alojar (de `faces url get`)
`--domain-id <id>`	Dominio personalizado en el que alojar (de `faces url get` o `faces domains create`)
`--api-key <key>`	Sobrescribe la API key

Proporciona exactamente uno de --subdomain-id o --domain-id. Ejemplos:

faces url set xK9mP2qR --path my-deck --subdomain-id sub_xxx
faces url set xK9mP2qR --path "" --domain-id dom_xxx

`subdomains create`

Crea un subdominio personalizado para el equipo del proyecto y luego conéctalo con faces url set. Requiere un plan de pago.

faces subdomains create <slug> --subdomain <label>

Opciones:

Flag	Descripción
`--subdomain <label>`	(requerido) Etiqueta del subdominio (letras minúsculas, números, guiones)
`--api-key <key>`	Sobrescribe la API key

`domains create`

Conecta un dominio personalizado y devuelve los registros DNS a agregar. Requiere un plan de pago.

faces domains create <slug> --hostname <host>

Opciones:

Flag	Descripción
`--hostname <host>`	(requerido) Dominio a conectar, sin protocolo ni `www` (por ejemplo, `example.com`)
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

faces domains create xK9mP2qR --hostname deck.example.com
faces domains create xK9mP2qR --hostname example.com | jq '.dns.recommendedRecords'

Una vez que el DNS se propague, ejecuta faces url set <slug> --path <p> --domain-id <id>.

`teams list`

Lista los equipos a los que tu API key puede acceder. El equipo personal se marca con isPersonal.

faces teams list

Ejemplos:

faces teams list
faces teams list | jq '.teams[] | select(.isPersonal == false)'

`slides list`

Lista todas las diapositivas de un proyecto.

faces slides list <slug>

Ejemplos:

faces slides list xK9mP2qR
faces slides list xK9mP2qR | jq '.slides[].id'

`slides get`

Lee los archivos fuente de una diapositiva (face.tsx, face.content.json, face.controls.json).

faces slides get <slug> <slide-id>

Ejemplos:

faces slides get xK9mP2qR abc123
faces slides get xK9mP2qR abc123 | jq '.files["face.tsx"]'

`slides create`

Crea una nueva diapositiva vacía. Devuelve el ID de la nueva diapositiva.

faces slides create <slug> --name "Slide Name"

Opciones:

Flag	Descripción
`--name <text>`	(requerido) Nombre visible para la nueva diapositiva
`--after <slide-id>`	Inserta después de esta diapositiva. Omite para agregar al final
`--editing`	Muestra inmediatamente el gradiente de carga en la nueva diapositiva. Llama a `slides finish-editing` cuando termines
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

faces slides create xK9mP2qR --name "Hero Section"
faces slides create xK9mP2qR --name "Features" --after abc123
faces slides create xK9mP2qR --name "Pricing" --editing

`slides reorder`

Reordena todas las diapositivas de un proyecto a un orden dado en una sola llamada atómica. La lista --ids debe contener exactamente los IDs de las diapositivas existentes del proyecto, en el orden final deseado.

faces slides reorder <slug> --ids <comma-separated-slide-ids>

Opciones:

Flag	Descripción
`--ids <slide-ids>`	(requerido) Lista ordenada completa, separada por comas, de todos los IDs de diapositiva existentes
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

faces slides reorder xK9mP2qR --ids face-abc,face-def,face-ghi

`slides update`

Actualiza los archivos fuente de una diapositiva. Solo se modifican los archivos proporcionados. El código se valida antes de guardar, devuelve errores si no compila.

faces slides update <slug> <slide-id> [options]

Opciones:

Flag	Descripción
`--tsx <file>`	Ruta al archivo face.tsx (o código inline)
`--content <file>`	Ruta al archivo face.content.json (o JSON inline)
`--controls <file>`	Ruta al archivo face.controls.json (o JSON inline)
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

# Actualizar el componente React
faces slides update xK9mP2qR abc123 --tsx ./my-slide.tsx

# Actualizar contenido y controles
faces slides update xK9mP2qR abc123 --content ./content.json --controls ./controls.json

# Actualizar los tres archivos
faces slides update xK9mP2qR abc123 --tsx ./face.tsx --content ./content.json --controls ./controls.json

`slides start-editing`

Muestra un indicador de carga en el editor mientras editas una diapositiva. Llámalo antes de hacer cambios, y siempre llama a finish-editing cuando termines.

faces slides start-editing <slug> <slide-id>

Opciones:

Flag	Descripción
`--api-key <key>`	Sobrescribe la API key

`slides finish-editing`

Limpia el indicador de carga de una diapositiva. Llama a este comando siempre después de editar, incluso si la edición falló.

faces slides finish-editing <slug> <slide-id>

`slides screenshot`

Captura una captura de pantalla JPEG de una diapositiva tal como se renderiza actualmente y devuelve una URL pública de CDN. Útil para verificar visualmente una diapositiva después de editarla.

faces slides screenshot <slug> <slide-id> [--mobile]

Opciones:

Flag	Descripción
`--mobile`	Captura el diseño móvil en lugar del de escritorio
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

faces slides screenshot xK9mP2qR abc123
faces slides screenshot xK9mP2qR abc123 --mobile
faces slides screenshot xK9mP2qR abc123 | jq -r '.screenshotUrl'

`slides guide`

Imprime la referencia de autoría de diapositivas, la misma guía que devuelven el server MCP y la API. Cubre la estructura de face.tsx, los tipos de bloque de face.content.json, los tipos de control de face.controls.json, tipografía, fuentes, CSS y ejemplos de código. Léelo antes de escribir código de diapositivas por primera vez.

faces slides guide [slug]

Opciones:

Flag	Descripción
`[slug]`	Slug de proyecto opcional. Adapta la guía al tamaño del lienzo móvil de ese proyecto
`--api-key <key>`	Sobrescribe la API key

Ejemplos:

# Guardar la guía en un archivo
faces slides guide | jq -r '.guide' > slide-guide.md

# Enviar directamente a un prompt de agente
faces slides guide | jq -r '.guide' | pbcopy

Referencia de archivos de diapositiva

Cada diapositiva está compuesta por tres archivos:

face.tsx (componente React)

import React from "react";
import { blocks } from "./face.content.json";
import { controls } from "./face.controls.json";
import { TextContent } from "@/components/ui/text-content";
import { Icon } from "@/components/ui/icon";

export default function HeroFace() {
  return (
    <div className="w-full h-full bg-background flex flex-col items-center justify-center p-16">
      <Icon name={blocks.heroIcon.name} size={48} className="text-primary mb-6" />
      <TextContent content={blocks.title.content} className="text-7xl font-bold text-center" />
      <TextContent content={blocks.subtitle.content} className="text-2xl text-muted-foreground mt-4" />
    </div>
  );
}

Reglas:

Debe exportar por defecto un componente React
El div externo debe tener w-full h-full (lienzo: 1920×1080 en escritorio, 384×683 en móvil)
Usa Tailwind CSS y container queries (@sm:, @md:, @lg:, @xl:) en lugar de media queries
Nunca incrustes texto en el código, guarda todo el texto visible para el usuario en face.content.json
Puedes importar cualquier paquete npm (se resuelve automáticamente, no necesitas instalarlo)
Disponibles: react, motion/react (Framer Motion), lucide-react, @base-ui/react/*
Componentes de UI: TextContent desde @/components/ui/text-content, Icon desde @/components/ui/icon

face.content.json (contenido editable)

{
  "blocks": {
    "heroIcon": { "type": "icon", "name": "sparkles" },
    "title": { "type": "text", "content": "Welcome to <strong>Faces</strong>" },
    "subtitle": { "type": "text", "content": "Build beautiful presentations" },
    "logo": { "type": "image", "src": "https://example.com/logo.png" }
  }
}

Tipos de bloque:

text: { "type": "text", "content": "HTML string" }, renderiza con <TextContent content={blocks.key.content} />
image: { "type": "image", "src": "url | null" }, renderiza con <img src={blocks.key.src} />
icon: { "type": "icon", "name": "lucide-icon-name" }, renderiza con <Icon name={blocks.key.name} />
table: { "type": "table", "columns": [...], "rows": [...] }, itera con blocks.key.rows.map(...)

face.controls.json (controles del editor)

{
  "controls": {
    "titleSize": { "type": "selector", "options": ["Medium", "Large", "Extra Large"], "value": "Large" },
    "showSubtitle": { "type": "switch", "value": true },
    "spacing": { "type": "slider", "min": 16, "max": 96, "step": 8, "value": 48 }
  }
}

Tipos de control:

slider: { "type": "slider", "min": 0, "max": 100, "step": 1, "value": 50 }
switch: { "type": "switch", "value": true }
selector: { "type": "selector", "options": ["A", "B"], "value": "A" }

Accede en face.tsx con: controls.key.value

Inicia sesión y guarda una API key.

faces login

Opciones:

Flag	Descripción
`--team <slug-or-id>`	Asocia la API key a un equipo específico (por defecto: tu equipo personal)
`--api-url <url>`	URL base de la API (por defecto: `FACES_API_URL` o `https://faces.app`)

Ejemplos:

faces login
faces login --team acme
faces login --team clxxx...

Abre tu navegador para autenticarte, luego guarda la key en ~/.config/faces/credentials.json. El valor de --team puede ser un slug o un id de equipo (consulta GET /api/v1/teams). Omite --team para asociar la key a tu equipo personal.

​new

​generate

​status

​list

​get

​rename

​duplicate

​publish

​unpublish

​config get

​config update

​url get

​url set

​subdomains create

​domains create

​teams list

​slides list

​slides get

​slides create

​slides reorder

​slides update

​slides start-editing

​slides finish-editing

​slides screenshot

​slides guide

​Referencia de archivos de diapositiva

​face.tsx (componente React)

​face.content.json (contenido editable)

​face.controls.json (controles del editor)

​login

`new`

`generate`

`status`

`list`

`get`

`rename`

`duplicate`

`publish`

`unpublish`

`config get`

`config update`

`url get`

`url set`

`subdomains create`

`domains create`

`teams list`

`slides list`

`slides get`

`slides create`

`slides reorder`

`slides update`

`slides start-editing`

`slides finish-editing`

`slides screenshot`

`slides guide`

Referencia de archivos de diapositiva

face.tsx (componente React)

face.content.json (contenido editable)

face.controls.json (controles del editor)

`login`