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'

`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 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 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

Opciones:

Flag	Descripción
`--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, 720×1280 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, @radix-ui/*
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.

Documentation Index

​new

​generate

​status

​list

​get

​slides list

​slides get

​slides create

​slides update

​slides start-editing

​slides finish-editing

​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`

`slides list`

`slides get`

`slides create`

`slides update`

`slides start-editing`

`slides finish-editing`

`slides guide`

Referencia de archivos de diapositiva

face.tsx — componente React

face.content.json — contenido editable

face.controls.json — controles del editor

`login`