Démarrage rapide avec la CLI dev
L’interface en ligne de commande (CLI) @facetapp/cli transforme un dossier
de build statique en révision déployée d’une app Facet. Il n’y a pas d’étape
d’installation : lancez chaque commande via pnpx. La CLI demande Node 20 ou
plus récent.
Pour les agentsà : tout le parcours tient en trois commandesà :
pnpx @facetapp/cli init, puispnpx @facetapp/cli login, puispnpx @facetapp/cli deploy --note "first build". La configuration se trouve dansfacet.config.json(clésapp,outDir) ; la session, dans~/.config/facet/auth.json(mode 600). Pour l’automatisation, mettez un token d’accès dansFACET_TOKEN; il gagne sur toute session enregistrée et n’est jamais rafraîchi. Le déploiement est unPOST /Api/app/:id/deploymultipartà ; la route répond{id, revision, activated, files}.
Quand l’utiliser
Section intitulée « Quand l’utiliser »Utilisez la CLI quandà :
- Vous déployez un premier build statique sur une instance Facet.
- Vous poussez un nouveau build depuis votre machine ou depuis l’intégration continue (CI).
- Vous listez les releases et ramenez un build défectueux en arrière.
Avant de commencer
Section intitulée « Avant de commencer »- Une instance Facet que vous pouvez joindre en HTTPS, et un compte dessus.
- Un rôle qui porte
deploysurapp.App. La CLI se connecte avec votre compte, et vous élisez un rôle sur l’écran de consentement. Le rôleadmincréé par l’initialisation portedeploy; le rôleeditorpré-créé non. - Un dossier de build statique. N’importe quel générateur de site statique convient.
- Node 20 ou plus récent.
1. Écrivez la configuration
Section intitulée « 1. Écrivez la configuration »pnpx @facetapp/cli initLa commande demande trois valeursà : le slug de l’app, le dossier de build et
l’URL de l’instance. Elle écrit facet.config.json à la racine du projet.
Avec une session enregistrée, init lit l’app par son slug. Quand cette app
n’existe pas, la CLI propose de la créer. La création demande write sur
app.App. Une app créée est un brouillon : activez-la dans le tableau de
bord avant le premier déploiement — voir
Enregistrer une app.
Sans session enregistrée, init écrit la configuration et s’arrête. Lancez
login ensuite.
2. Connectez-vous
Section intitulée « 2. Connectez-vous »pnpx @facetapp/cli loginLa commande ouvre un navigateur sur l’écran de consentement OAuth. Le flux est celui du code d’autorisation avec PKCE (Proof Key for Code Exchange). La méthode de challenge est S256. La CLI démarre un serveur de bouclage à usage unique et y reçoit le code.
La CLI se connecte par l’enregistrement facet-cli pré-créé. Cet
enregistrement n’accepte que des adresses de redirection en bouclageà :
http://localhost:*, http://127.0.0.1:* et http://[::1]:*.
La session atterrit dans ~/.config/facet/auth.json avec le mode 600.
$XDG_CONFIG_HOME déplace l’emplacement. Le fichier porte une entrée par URL
d’instance.
3. Construisez et déployez
Section intitulée « 3. Construisez et déployez »Construisez votre app avec n’importe quel générateur de site statique. Puis lancezà :
pnpx @facetapp/cli deploy --note "first build"La commande parcourt le dossier de build. Elle saute node_modules, .git et
.DS_Store. Elle téléverse une requête multipart et active la nouvelle
révision. Elle affiche la révision attribuée et l’URL de l’appà ; le schéma et
le port suivent l’URL de l’instance.
Passez --no-activate pour téléverser une révision qui reste dormanteà :
pnpx @facetapp/cli deploy --no-activate4. Vérifiez la session
Section intitulée « 4. Vérifiez la session »pnpx @facetapp/cli whoamiLa commande affiche l’instance, le compte derrière le token enregistré, le rôle actif et la révision active de l’app.
5. Gérez les releases
Section intitulée « 5. Gérez les releases »pnpx @facetapp/cli releasesLa liste montre les déploiements de l’app, de la révision la plus récente à
la plus ancienne. Le déploiement actif porte un *.
Ramenez un build défectueux en arrière par révision :
pnpx @facetapp/cli rollback 2La commande pointe active_deployment vers le déploiement de révision 2.
Une révision inconnue échoue avec la liste de celles qui existent.
Déconnectez-vous quand vous avez finià :
pnpx @facetapp/cli logoutLa commande retire la session enregistrée de l’instance. Elle est idempotente.
6. Déployez depuis la CI
Section intitulée « 6. Déployez depuis la CI »Mettez un token d’accès dans l’environnement de la CIà:
export FACET_TOKEN="paste-an-access-token"pnpx @facetapp/cli deploy --note "ci build 42"Le token d’environnement gagne sur toute session enregistrée. La CLI ne le rafraîchit jamais. À son expiration, l’exécution échoue avec l’invite de reconnexion. Mettez un token neuf dans le secret CI avant la prochaine exécution.
Ce facet.config.json configure deux ciblesà :
{ "app": "myapp", "outDir": "dist", "spa": true, "targets": { "staging": { "url": "https://staging.facet.example.tld" }, "prod": { "url": "https://facet.example.tld" } }, "defaultTarget": "staging"}| Champ | Requis | Signification |
|---|---|---|
app |
oui | Le slug de l’app sur l’instance Facet, par exemple myapp. |
outDir |
oui | Le dossier de build à téléverser, relatif à la racine du projet. |
spa |
non | Indique si le déploiement se comporte comme une app monopage. Par défaut true. |
targets |
non | Des instances Facet nommées. Chacune porte une url. |
defaultTarget |
non | La cible employée quand aucun drapeau --target n’est passé. |
Choisissez une cible avec --target :
pnpx @facetapp/cli deploy --target prod --note "release 1.0"Sans le drapeau, la CLI emploie defaultTarget. Sans les deux, la commande
échoue et liste les cibles disponibles.
Dépannage
Section intitulée « Dépannage »La CLI affiche un message par échecà :
| Message | Cause et étape suivante |
|---|---|
No facet.config.json in <root> |
Pas de fichier de configuration. Lancez init ou placez-vous à la racine du projet. |
facet.config.json is not valid JSON |
Corrigez la syntaxe JSON. |
has no "app"/"outDir" value |
Renseignez le champ manquant dans facet.config.json. |
Unknown target "x"… Available targets: … |
--target ou defaultTarget ne nomme rien. Employez un nom listé. |
No stored session for <instance> |
Non connecté. Lancez login. |
Run "pnpx @facetapp/cli login" to sign in again. |
La session a expiré ou a été révoquée, et le refresh a échoué. Reconnectez-vous. |
No app with slug "x" on <instance> |
Le slug app de la configuration ne correspond à aucune app de l’instance. Créez-la ou corrigez le slug. |
The build folder "x" does not exist |
outDir pointe vers un dossier absent. Vérifiez la configuration. |
holds no files to deploy |
Le dossier de build est vide. Construisez d’abord. |
HTTP 422 from /api/app/…/deploy: … |
Le serveur a refusé le téléversement. Une app en brouillon ou désactivée est la cause habituelleà ; un chemin de fichier refusé est l’autre. |
Cannot reach <instance> |
Échec réseau. Vérifiez l’URL et la connectivité. |
Une app neuve répond sans fin HTTP 422 au déploiement.
Une app créée reste un brouillon jusqu’à ce qu’un opérateur l’active. Activez l’app dans le tableau de bord, puis déployez de nouveau. Voir Enregistrer une app.
Une exécution CI échoue avec l’invite de reconnexion.
FACET_TOKEN a expiré. La CLI ne rafraîchit jamais un token d’environnement.
Mettez un token d’accès neuf dans le secret CI.
Voir aussi
Section intitulée « Voir aussi »- Déployer votre frontend — le modèle de déploiement derrière ces commandes.
- Enregistrer une app — le statut de l’app, le brouillon et l’activation.
- Le SDK TypeScript (
@facetapp/sdk) — appelez l’API depuis le code de l’app. - Le README de la CLI sur GitHubà : packages/cli/README.md.
- Le contrat du backend sur GitHubà : doc/packages/cli.md.