Commandes du CLI - Faces Docs

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

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 :

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

Exemples :

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.

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 :

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

Exemples :

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

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 :

# Vérification ponctuelle
faces status cm1abc123...

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

`list`

Liste vos projets.

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 :

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

`get`

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

faces get <slug>

Exemples :

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.

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.

faces duplicate <slug>

Exemples :

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

`publish`

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

faces publish <slug>

Exemples :

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.

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

faces config get <slug>

Exemples :

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

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 :

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.

faces url get <slug>

Exemples :

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.

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 :

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.

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.

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 :

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.

faces teams list

Exemples :

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

`slides list`

Liste toutes les diapositives d’un projet.

faces slides list <slug>

Exemples :

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

faces slides get <slug> <slide-id>

Exemples :

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.

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 :

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

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 :

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.

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 :

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

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

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.

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 :

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.

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 :

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

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)

{
  "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)

{
  "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

Se connecter et enregistrer une clé API.

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 :

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.

​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

​Référence des fichiers de diapositive

​face.tsx (composant React)

​face.content.json (contenu modifiable)

​face.controls.json (contrôles de l’éditeur)

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

Référence des fichiers de diapositive

face.tsx (composant React)

face.content.json (contenu modifiable)

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

`login`