> ## Documentation Index
> Fetch the complete documentation index at: https://faces.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Comandos del CLI

> Referencia completa de todos los comandos del CLI de Faces.

## `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](/es/authentication#teams-and-keys)).

```bash theme={null}
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:**

```json theme={null}
{
  "projectId": "cm1abc123...",
  "projectSlug": "xK9mP2qR",
  "projectVersionId": "cm1ver456...",
  "editorUrl": "https://faces.app/s/xK9mP2qR"
}
```

**Ejemplos:**

```bash theme={null}
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.

```bash theme={null}
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:**

```json theme={null}
{
  "jobId": "cm1abc123...",
  "status": "processing",
  "editorUrl": "https://faces.app/s/xK9mP2qR"
}
```

**Ejemplos:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# Verificar una vez
faces status cm1abc123...

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

***

## `list`

Lista tus proyectos.

```bash theme={null}
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:**

```bash theme={null}
faces list --published --limit 5
faces list | jq '.projects[].slug'
```

***

## `get`

Obtiene los detalles de un proyecto específico.

```bash theme={null}
faces get <slug>
```

**Ejemplos:**

```bash theme={null}
faces get xK9mP2qR
faces get xK9mP2qR | jq '.publishedUrl'
```

***

## `rename`

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

```bash theme={null}
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.

```bash theme={null}
faces duplicate <slug>
```

**Ejemplos:**

```bash theme={null}
faces duplicate xK9mP2qR
faces duplicate xK9mP2qR | jq -r '.editorUrl'
```

***

## `publish`

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

```bash theme={null}
faces publish <slug>
```

**Ejemplos:**

```bash theme={null}
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.

```bash theme={null}
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).

```bash theme={null}
faces config get <slug>
```

**Ejemplos:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
faces url get <slug>
```

**Ejemplos:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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`.

```bash theme={null}
faces teams list
```

**Ejemplos:**

```bash theme={null}
faces teams list
faces teams list | jq '.teams[] | select(.isPersonal == false)'
```

***

## `slides list`

Lista todas las diapositivas de un proyecto.

```bash theme={null}
faces slides list <slug>
```

**Ejemplos:**

```bash theme={null}
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).

```bash theme={null}
faces slides get <slug> <slide-id>
```

**Ejemplos:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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ó.

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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)

```tsx theme={null}
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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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`

***

## `login`

Inicia sesión y guarda una API key.

```bash theme={null}
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:**

```bash theme={null}
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.