> ## 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.

# Commandes du CLI

> Référence complète de toutes les commandes du CLI Faces.

## `new`

Crée un nouveau projet vide. Renvoie le `projectSlug` et l'`editorUrl`. Ajoutez des diapositives avec `faces slides create` + `faces slides update`. Le projet est créé sous l'équipe à laquelle votre clé API est associée (voir [Authentification](/fr/authentication#teams-and-keys)).

```bash theme={null}
faces new
```

**Options :**

| Flag              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `--name <text>`   | Nom d'affichage du nouveau projet (par défaut : `Untitled`) |
| `--api-key <key>` | Remplace la clé API                                         |

**Sortie :**

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

**Exemples :**

```bash theme={null}
faces new
faces new --name "Q4 Roadmap"
```

***

## `generate`

Génère une nouvelle présentation interactive à partir d'un prompt textuel. Décrivez ce que vous voulez (un pitch, un portfolio, un guide ou une proposition) et Faces s'occupe du contenu, des animations et de la mise en page.

```bash theme={null}
faces generate --prompt "5-slide pitch deck about AI in healthcare"
```

**Options :**

| Flag              | Description                                       |
| ----------------- | ------------------------------------------------- |
| `--prompt <text>` | **(obligatoire)** Description du projet à générer |
| `--template <id>` | Utiliser un projet existant comme template        |
| `--wait`          | Attendre que le projet termine sa génération      |
| `--api-key <key>` | Remplace la clé API                               |

**Sortie :**

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

**Exemples :**

```bash theme={null}
# Génération basique
faces generate --prompt "Company intro deck with 3 slides"

# Avec un template
faces generate --prompt "Same deck for fintech" --template cm1xyz789

# Attendre la fin
faces generate --prompt "Team intro" --wait
```

***

## `status`

Vérifie le statut d'un job de génération.

```bash theme={null}
faces status <job-id>
```

**Options :**

| Flag              | Description                                         |
| ----------------- | --------------------------------------------------- |
| `--wait`          | Interroge jusqu'à ce que le job réussisse ou échoue |
| `--api-key <key>` | Remplace la clé API                                 |

**Exemples :**

```bash theme={null}
# Vérification ponctuelle
faces status cm1abc123...

# Attendre la fin
faces status cm1abc123... --wait
```

***

## `list`

Liste vos projets.

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

**Options :**

| Flag              | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `--published`     | Affiche uniquement les projets publiés                   |
| `--limit <n>`     | Nombre maximum de résultats (par défaut : 20, max : 100) |
| `--api-key <key>` | Remplace la clé API                                      |

**Exemples :**

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

***

## `get`

Récupère les détails d'un projet spécifique.

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

**Exemples :**

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

***

## `rename`

Renomme un projet. Modifie uniquement le nom d'affichage ; le slug et les URLs restent identiques.

```bash theme={null}
faces rename <slug> --name "New Name"
```

**Options :**

| Flag              | Description                               |
| ----------------- | ----------------------------------------- |
| `--name <text>`   | **(obligatoire)** Nouveau nom d'affichage |
| `--api-key <key>` | Remplace la clé API                       |

***

## `duplicate`

Crée une copie complète d'un projet, y compris toutes ses diapositives. La copie obtient son propre slug et une nouvelle URL non publiée.

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

**Exemples :**

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

***

## `publish`

Publie la dernière version d'un projet sur son URL en direct.

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

**Exemples :**

```bash theme={null}
faces publish xK9mP2qR
faces publish xK9mP2qR | jq -r '.publishedUrl'
```

***

## `unpublish`

Met un projet publié hors ligne. Le projet et ses diapositives sont conservés et peuvent être republiés ultérieurement.

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

***

## `config get`

Lit le fichier `project.config.json` d'un projet, y compris ses paramètres de mise en page et les design tokens partagés (palette et polices).

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

**Exemples :**

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

***

## `config update`

Fusionne des clés dans `project.config.json`. Utilisez cette commande pour définir les design tokens du projet. Seules les clés que vous passez sont modifiées ; le reste est préservé.

```bash theme={null}
faces config update <slug> --config <json-or-file>
```

**Options :**

| Flag                      | Description                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `--config <json-or-file>` | **(obligatoire)** Un objet JSON ou un chemin vers un fichier JSON contenant les clés de config à fusionner |
| `--api-key <key>`         | Remplace la clé API                                                                                        |

**Exemples :**

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

***

## `url get`

Récupère la configuration d'URL actuelle d'un projet ainsi que les sous-domaines et domaines disponibles pour en changer.

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

**Exemples :**

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

***

## `url set`

Modifie le chemin, change de sous-domaine, ou pointe le projet vers un domaine personnalisé. Nécessite un forfait payant.

```bash theme={null}
faces url set <slug> --path <p> [--subdomain-id <id> | --domain-id <id>]
```

**Options :**

| Flag                  | Description                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| `--path <p>`          | **(obligatoire)** Segment de chemin après le nom d'hôte (utilisez `""` pour la racine) |
| `--subdomain-id <id>` | Sous-domaine à héberger (depuis `faces url get`)                                       |
| `--domain-id <id>`    | Domaine personnalisé à héberger (depuis `faces url get` ou `faces domains create`)     |
| `--api-key <key>`     | Remplace la clé API                                                                    |

Fournissez exactement l'un de `--subdomain-id` ou `--domain-id`.

**Exemples :**

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

Crée un sous-domaine personnalisé pour l'équipe du projet, puis connectez-le avec `faces url set`. Nécessite un forfait payant.

```bash theme={null}
faces subdomains create <slug> --subdomain <label>
```

**Options :**

| Flag                  | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `--subdomain <label>` | **(obligatoire)** Label du sous-domaine (lettres minuscules, chiffres, tirets) |
| `--api-key <key>`     | Remplace la clé API                                                            |

***

## `domains create`

Connecte un domaine personnalisé et renvoie les enregistrements DNS à ajouter. Nécessite un forfait payant.

```bash theme={null}
faces domains create <slug> --hostname <host>
```

**Options :**

| Flag                | Description                                                                            |
| ------------------- | -------------------------------------------------------------------------------------- |
| `--hostname <host>` | **(obligatoire)** Domaine à connecter, sans protocole ni `www` (par ex. `example.com`) |
| `--api-key <key>`   | Remplace la clé API                                                                    |

**Exemples :**

```bash theme={null}
faces domains create xK9mP2qR --hostname deck.example.com
faces domains create xK9mP2qR --hostname example.com | jq '.dns.recommendedRecords'
```

Une fois le DNS propagé, exécutez `faces url set <slug> --path <p> --domain-id <id>`.

***

## `teams list`

Liste les équipes auxquelles votre clé API a accès. L'équipe personnelle est signalée par `isPersonal`.

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

**Exemples :**

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

***

## `slides list`

Liste toutes les diapositives d'un projet.

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

**Exemples :**

```bash theme={null}
faces slides list xK9mP2qR
faces slides list xK9mP2qR | jq '.slides[].id'
```

***

## `slides get`

Lit les fichiers source d'une diapositive (face.tsx, face.content.json, face.controls.json).

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

**Exemples :**

```bash theme={null}
faces slides get xK9mP2qR abc123
faces slides get xK9mP2qR abc123 | jq '.files["face.tsx"]'
```

***

## `slides create`

Crée une nouvelle diapositive vide. Renvoie l'ID de la nouvelle diapositive.

```bash theme={null}
faces slides create <slug> --name "Slide Name"
```

**Options :**

| Flag                 | Description                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--name <text>`      | **(obligatoire)** Nom d'affichage de la nouvelle diapositive                                                                 |
| `--after <slide-id>` | Insère après cette diapositive. Omettez pour ajouter à la fin                                                                |
| `--editing`          | Affiche immédiatement le dégradé de chargement sur la nouvelle diapositive. Appelez `slides finish-editing` une fois terminé |
| `--api-key <key>`    | Remplace la clé API                                                                                                          |

**Exemples :**

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

Réordonne toutes les diapositives d'un projet selon un ordre donné, en un seul appel atomique. La liste `--ids` doit contenir exactement les IDs des diapositives existantes du projet, dans l'ordre final souhaité.

```bash theme={null}
faces slides reorder <slug> --ids <comma-separated-slide-ids>
```

**Options :**

| Flag                | Description                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| `--ids <slide-ids>` | **(obligatoire)** Liste ordonnée complète, séparée par des virgules, de tous les IDs de diapositive existants |
| `--api-key <key>`   | Remplace la clé API                                                                                           |

**Exemples :**

```bash theme={null}
faces slides reorder xK9mP2qR --ids face-abc,face-def,face-ghi
```

***

## `slides update`

Met à jour les fichiers source d'une diapositive. Seuls les fichiers fournis sont modifiés. Le code est validé avant l'enregistrement et renvoie des erreurs s'il ne compile pas.

```bash theme={null}
faces slides update <slug> <slide-id> [options]
```

**Options :**

| Flag                | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `--tsx <file>`      | Chemin vers le fichier face.tsx (ou code inline)           |
| `--content <file>`  | Chemin vers le fichier face.content.json (ou JSON inline)  |
| `--controls <file>` | Chemin vers le fichier face.controls.json (ou JSON inline) |
| `--api-key <key>`   | Remplace la clé API                                        |

**Exemples :**

```bash theme={null}
# Mettre à jour le composant React
faces slides update xK9mP2qR abc123 --tsx ./my-slide.tsx

# Mettre à jour le contenu et les contrôles
faces slides update xK9mP2qR abc123 --content ./content.json --controls ./controls.json

# Mettre à jour les trois fichiers
faces slides update xK9mP2qR abc123 --tsx ./face.tsx --content ./content.json --controls ./controls.json
```

***

## `slides start-editing`

Affiche un indicateur de chargement dans l'éditeur pendant l'édition d'une diapositive. À appeler avant de faire des modifications, et appelez toujours `finish-editing` une fois terminé.

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

**Options :**

| Flag              | Description         |
| ----------------- | ------------------- |
| `--api-key <key>` | Remplace la clé API |

***

## `slides finish-editing`

Efface l'indicateur de chargement pour une diapositive. Appelez toujours cette commande après l'édition, même si l'édition a échoué.

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

***

## `slides screenshot`

Capture une capture d'écran JPEG d'une diapositive telle qu'elle est actuellement rendue et renvoie une URL CDN publique. Utile pour vérifier visuellement une diapositive après l'avoir éditée.

```bash theme={null}
faces slides screenshot <slug> <slide-id> [--mobile]
```

**Options :**

| Flag              | Description                                       |
| ----------------- | ------------------------------------------------- |
| `--mobile`        | Capture la mise en page mobile au lieu du desktop |
| `--api-key <key>` | Remplace la clé API                               |

**Exemples :**

```bash theme={null}
faces slides screenshot xK9mP2qR abc123
faces slides screenshot xK9mP2qR abc123 --mobile
faces slides screenshot xK9mP2qR abc123 | jq -r '.screenshotUrl'
```

***

## `slides guide`

Affiche la référence de création de diapositive : le même guide renvoyé par le server MCP et l'API. Couvre la structure de `face.tsx`, les types de blocs de `face.content.json`, les types de contrôles de `face.controls.json`, la typographie, les polices, le CSS et des exemples de code. Lisez-le avant d'écrire du code de diapositive pour la première fois.

```bash theme={null}
faces slides guide [slug]
```

**Options :**

| Flag              | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `[slug]`          | Slug de projet optionnel ; adapte le guide à la taille du canvas mobile de ce projet |
| `--api-key <key>` | Remplace la clé API                                                                  |

**Exemples :**

```bash theme={null}
# Sauvegarder le guide dans un fichier
faces slides guide | jq -r '.guide' > slide-guide.md

# Le copier directement dans un prompt d'agent
faces slides guide | jq -r '.guide' | pbcopy
```

***

## Référence des fichiers de diapositive

Chaque diapositive est composée de trois fichiers :

### face.tsx (composant 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>
  );
}
```

**Règles :**

* Doit exporter par défaut un composant React
* Le div extérieur doit avoir `w-full h-full` (canvas : 1920×1080 desktop, 384×683 mobile)
* Utilisez Tailwind CSS et les container queries (`@sm:`, `@md:`, `@lg:`, `@xl:`) au lieu des media queries
* Ne codez jamais le texte en dur. Stockez tout le texte visible par l'utilisateur dans face.content.json
* Vous pouvez importer n'importe quel package npm (résolu automatiquement, aucune installation requise)
* Disponibles : `react`, `motion/react` (Framer Motion), `lucide-react`, `@base-ui/react/*`
* Composants UI : `TextContent` depuis `@/components/ui/text-content`, `Icon` depuis `@/components/ui/icon`

### face.content.json (contenu modifiable)

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

**Types de blocs :**

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

### face.controls.json (contrôles de l'éditeur)

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

**Types de contrôles :**

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

Accès dans face.tsx : `controls.key.value`

***

## `login`

Se connecter et enregistrer une clé API.

```bash theme={null}
faces login
```

**Options :**

| Flag                  | Description                                                                        |
| --------------------- | ---------------------------------------------------------------------------------- |
| `--team <slug-or-id>` | Associe la clé API à une équipe spécifique (par défaut : votre équipe personnelle) |
| `--api-url <url>`     | URL de base de l'API (par défaut : `FACES_API_URL` ou `https://faces.app`)         |

**Exemples :**

```bash theme={null}
faces login
faces login --team acme
faces login --team clxxx...
```

Ouvre votre navigateur pour vous authentifier, puis enregistre la clé dans `~/.config/faces/credentials.json`. La valeur de `--team` peut être un slug ou un id d'équipe (voir `GET /api/v1/teams`). Omettez `--team` pour associer la clé à votre équipe personnelle.