#Commandes

Six commandes, plus aide. Chacune a un alias anglais, et deux en ont un second. La casse est ignorée : Pousser et PUSH désignent la même chose.

Commande	Alias	Ce qu’elle fait	Portée exigée
`connexion`	`login`	enregistre une clé d’API sur cette machine	—
`lister`	`list`	les thèmes du site	`lecture`
`recuperer`	`pull`, `récupérer`	écrit un thème distant dans un dossier local	`lecture`
`pousser`	`push`	envoie les fichiers qui ont changé	`themes`
`suivre`	`dev`, `watch`	pousse chaque fichier à la sauvegarde	`themes`
`publier`	`publish`	met un thème en ligne	`themes`
`aide`	`help`	ce tableau, ou l’aide d’une commande	—

Il n’y a aucun argument positionnel en dehors du nom de la commande — et d’un sujet facultatif pour aide. Tout le reste passe par des options --nom=valeur.

#Options globales

Elles valent pour toutes les commandes, et sont toujours prioritaires sur les fichiers de configuration. L’ordre complet est décrit dans Configuration.

--siteslug ou uuid

Le site visé. Défaut : le premier site accessible à la clé — un ordre qui change dès qu’un site s’ajoute au compte, d’où l’intérêt de le figer. L’option désigne le site, elle ne l’autorise pas : le serveur revalide toujours contre les sites du porteur, et refuse en site_interdit.

--urladressedéfaut : http://localhost:3000

L’adresse du CMS. En production, https://cms.webcosa.com. Les barres obliques finales sont retirées.

--themeuuid, préfixe ou nom

Le thème visé. Trois formes acceptées : l’identifiant complet, le préfixe de huit caractères qu’affiche lister, ou le nom exact. Sans cette option et avec un seul thème sur le site, c’est celui-là ; avec plusieurs, la commande refuse plutôt que de deviner.

--dossierchemin

Le dossier de travail, résolu depuis le dossier courant. Sans lui : le dossier qui contient le .webcosa.json trouvé, sinon themes/<nom-du-thème> sous le dossier courant.

--verbeuxdrapeaudéfaut : false

Détaille chaque appel HTTP sur la sortie d’erreur, liste les fichiers inchangés d’un pousser, et rend la trace technique d’une erreur inattendue.

--aidedrapeaudéfaut : false

Affiche l’aide de la commande et sort, sans contacter le serveur.

Danger

Il n’existe pas d’option --cle=. Une clé passée sur la ligne de commande entre dans l’historique du shell et dans la liste des processus, où n’importe quel autre compte de la machine peut la lire. La clé vient de ~/.webcosa/config.json ou de WEBCOSA_CLE, et de nulle part ailleurs.

#`connexion`

Enregistre une clé d’API sur cette machine. C’est la seule commande qui fonctionne sans clé — c’est elle qui en pose une. Le parcours complet, avec la création de la clé côté CMS, est sur Connexion.

$node scripts/theme.mjs connexion [--url=<adresse>] [--site=<slug>]$node scripts/theme.mjs connexion --depuis-stdin < cle.txt

--depuis-stdindrapeaudéfaut : false

Lit la clé sur l’entrée standard au lieu de la demander, et ne pose aucune question — l’adresse vient alors de --url, de WEBCOSA_URL ou du défaut. Pour les environnements sans terminal.

--siteslug ou uuid

Écrit aussi dans le fichier de configuration global. Voir l’encadré ci-dessous : ce champ n’est aujourd’hui pas relu.

$node scripts/theme.mjs connexion --url=https://cms.webcosa.com

✓ Clé enregistrée dans /Users/marc/.webcosa/config.json (0600)
https://cms.webcosa.com — site Menuiserie Dubois (dubois), 2 thèmes visibles.
Thème publié : Origo

Attention

connexion --site= inscrit bien le site dans ~/.webcosa/config.json, mais le CLI ne relit pas ce champ : le site est cherché dans --site, puis WEBCOSA_SITE, puis .webcosa.json, et s’arrête là. Pour figer un site durablement, mets-le dans le .webcosa.json du thème — ce que recuperer fait d’ailleurs tout seul.

#`lister`

Les thèmes du site, le publié en tête et en évidence.

$node scripts/theme.mjs lister [--site=<slug>]

Aucune option propre.

$node scripts/theme.mjs lister

  id        nom       version  rôle       modifié
11111111  Origo     1.0.0    publié     il y a 3 min
22222222  Chantier  2.1.0    brouillon  il y a 4 j

L’identifiant court des huit premiers caractères suffit partout où l’on attend un --theme=. Le nom exact aussi. Un site sans thème affiche Aucun thème sur ce site. et sort en succès — ce n’est pas une erreur.

#`recuperer`

Écrit un thème distant dans un dossier local, et y pose un .webcosa.json : les commandes suivantes n’ont plus besoin d’aucune option.

$node scripts/theme.mjs recuperer [--theme=<id|nom>] [--dossier=<chemin>] [--force]

--dossierchemin

Où écrire. Sans lui, themes/<nom-du-thème> sous le dossier courant — un défaut qui ne vaut qu’en dehors du dépôt : à la racine du dépôt, il viserait le dossier des thèmes d’origine, et le CLI t’en avertit.

--forcedrapeaudéfaut : false

Écrase sans poser de question les fichiers locaux qui diffèrent du distant.

$node scripts/theme.mjs recuperer --theme=Origo --dossier=~/themes/origo

✓ 24 fichiers de « Origo » écrits dans /Users/marc/themes/origo
.webcosa.json y a été posé : les prochaines commandes n'ont plus besoin d'options.
Édite, puis : node scripts/theme.mjs pousser --dossier=/Users/marc/themes/origo

Danger

recuperer écrase le disque. Les fichiers locaux qui diffèrent du distant sont d’abord listés, puis la commande demande confirmation :

bash

! 2 fichier(s) local(aux) diffèrent du distant et seraient écrasés :
    assets/theme.css
    sections/hero.liquid

Écraser ces fichiers ? [o/N]

Répondre non interrompt tout : Récupération annulée, rien n'a été écrit. --force passe outre sans rien demander.

Perdre du travail local non poussé est le pire échec possible d’un outil comme celui-ci : il n’y a pas d’annulation, pas de corbeille, et l’on ne saurait même pas ce qu’on a perdu. C’est le seul endroit où l’on préfère être bavard.

Note

Tous les chemins reçus du serveur sont validés avant la première écriture. Un serveur est de confiance, mais un outil qui écrit sur le disque de son utilisateur d’après une réponse réseau ne doit pas être celui qui découvre la traversée de chemin : ../../.ssh/authorized_keys reçu dans un JSON s’écrirait très bien sans ce contrôle. Un chemin douteux interrompt tout, et rien n’est écrit.

#`pousser`

Compare les empreintes SHA-256 locales à celles du serveur et n’envoie que ce qui a changé.

$node scripts/theme.mjs pousser [--theme=<id|nom>] [--dossier=<chemin>] [--supprimer] [--force] [--nouveau] [--nom=<nom>]

--supprimerdrapeaudéfaut : false

Retire du thème distant les fichiers absents en local. Les liste et demande confirmation avant de les effacer.

--forcedrapeaudéfaut : false

Supprime sans poser la question. N’a d’effet qu’avec --supprimer, et n’existe que pour l’intégration continue, qui n’a pas de terminal pour répondre.

--nouveaudrapeaudéfaut : false

Crée un thème neuf à partir du dossier, au lieu de mettre à jour l’existant. Le dossier visé est alors --dossier, le dossier du .webcosa.json trouvé, ou à défaut le dossier courant — pas themes/<nom>.

--nomchaîne

Le nom du thème créé par --nouveau, tronqué à 80 caractères. Par défaut, celui du champ nom de config/theme.json, sinon le nom du dossier.

$node scripts/theme.mjs pousser

Origo · /Users/marc/themes/origo

↑ modifié   assets/theme.css
+ nouveau   sections/temoignages.liquid

✓ 1 nouveau, 1 modifié, 22 inchangés

Les fichiers sont envoyés un par un et dans l’ordre, jamais en rafale : chaque écriture valide la syntaxe côté serveur, et quand l’une échoue on veut savoir exactement lesquelles étaient passées. Une erreur de syntaxe interrompt donc l’envoi, en nommant le fichier fautif :

Sortie du CLIbash

✗ sections/hero.liquid — tag "for" not closed, line:14, col:1 [syntaxe]

Quand rien n’a changé, la commande liste les fichiers inchangés plutôt que de n’afficher qu’une ligne — pour qu’on voie tout de suite qu’elle a bien regardé le bon dossier.

#Les fichiers orphelins

Un fichier présent à distance mais absent en local est signalé, pas supprimé :

Sortie du CLIbash

! 1 fichier(s) existent à distance mais pas en local — non touchés :
    sections/promo.liquid
    Ajoute `--supprimer` pour les retirer du thème distant.

Danger

--supprimer détruit du travail qui n’existe qu’en base. Pas de corbeille, pas d’historique, pas de version précédente. Le cas réel n’a rien d’exotique : un collègue ajoute une section depuis l’éditeur du CMS, tu pousses un dossier récupéré la veille, son travail disparaît.

D’où l’annonce avant l’action, et la question :

bash

! 1 fichier(s) vont être SUPPRIMÉS du thème distant « Origo » :
    sections/promo.liquid
    Ils n'existent qu'en base : la suppression est définitive.

Supprimer ces fichiers ? [o/N]

Répondre non n’annule pas les fichiers déjà poussés : Suppression annulée — les fichiers poussés ci-dessus, eux, sont bien enregistrés.

--force supprime sans question. Réserve-le à l’intégration continue, où confirmer() rendrait false faute de terminal et ferait échouer la commande.

#Créer un thème avec `--nouveau`

Le dossier est empaqueté en archive et envoyé à POST /api/themes/importer.

$node scripts/theme.mjs pousser --nouveau --nom="Atelier v2" --dossier=~/themes/atelier

✓ Thème « Atelier v2 » créé — 24 fichiers
identifiant : 33333333-3333-4333-8333-333333333333
Il arrive en BROUILLON : il ne remplace pas encore celui que voient les visiteurs.
Pour le publier : node scripts/theme.mjs publier --theme=33333333-3333-4333-8333-333333333333

L’archive doit contenir les trois fichiers indispensables — layout/theme.liquid, config/settings_schema.json, templates/index.json — sans quoi le serveur refuse l’import entier.

#`suivre`

Surveille le dossier et pousse chaque fichier à la sauvegarde, avec l’heure. Ctrl+C pour sortir.

$node scripts/theme.mjs suivre [--theme=<id|nom>] [--dossier=<chemin>] [--oui-je-sais]

--oui-je-saisdrapeaudéfaut : false

Accepte de suivre le thème publié, sans proposer de le dupliquer. À taper en connaissance de cause.

$node scripts/theme.mjs suivre

Origo · brouillon
/Users/marc/themes/origo — 24 fichiers suivis
Aperçu : https://cms.webcosa.com/s/dubois
Ce thème est un brouillon : il ne remplace pas celui que voient les visiteurs.
Ctrl+C pour arrêter.

14:32:07  ↑ sections/hero.liquid
14:32:41  ↑ assets/theme.css

Trois comportements à connaître, tous délibérés :

Une erreur n’arrête pas le suivi. Une accolade pas encore refermée pendant la frappe est un état normal du travail ; sortir obligerait à relancer la commande toutes les deux minutes. Le message s’affiche, le suivi continue.
Un fichier supprimé en local n’est pas supprimé à distance. Un éditeur qui remplace un fichier par un temporaire le fait disparaître une fraction de seconde, et ce clignotement ne doit rien effacer en base. La ligne ? disparu te le rappelle, avec la commande à taper si c’est voulu.
Les sauvegardes sont dédoublonnées. Un éditeur émet deux à quatre événements pour un seul enregistrement ; un anti-rebond de 120 ms par fichier évite quatre écritures identiques en base.

Attention

Suivre un thème publié est refusé sans --oui-je-sais : ce serait modifier en direct le site que voient les clients à chaque Cmd+S, y compris pendant les vingt secondes où une balise n’est pas refermée.

bash

! « Origo » est le thème PUBLIÉ : chaque sauvegarde irait en ligne.

En dupliquer une copie brouillon et suivre la copie ? [o/N] o
✓ Copie créée : Origo (copie) 44444444-4444-4444-8444-444444444444

Accepter la copie met à jour le .webcosa.json du dossier au passage : sans cela, le pousser suivant repartirait sur le thème publié — exactement ce qu’on vient d’éviter. Refuser interrompt : Suivi annulé.

#`publier`

Met un thème en ligne, après confirmation. C’est le seul geste du CLI que voient les visiteurs du site.

$node scripts/theme.mjs publier [--theme=<id|nom>]

Aucune option propre.

$node scripts/theme.mjs publier --theme=22222222

  Publier, c'est changer ce que voient les visiteurs du site.
  en ligne aujourd'hui : Origo
  remplacé par         : Chantier 22222222

Confirmer la publication ? [o/N] o
✓ « Chantier » est en ligne.

Publier un thème déjà publié n’est pas une erreur : la commande affiche « Chantier » est déjà le thème publié. et s’arrête.

Attention

publier ne s’automatise pas. La confirmation n’a pas de drapeau de contournement, et confirmer() rend false sans terminal : lancée dans une intégration continue, la commande s’arrêtera toujours sur Publication annulée. C’est voulu — le déploiement d’un thème peut être automatique, sa mise en ligne reste une décision.

Le retour arrière consiste à republier l’ancien thème, qui n’a pas bougé : le brouillon et le publié coexistent. Voir Publier.

#`aide`

$node scripts/theme.mjs aide$node scripts/theme.mjs aide pousser$node scripts/theme.mjs pousser --aide

Argument

commandenom ou alias

Le sujet de l’aide. Absent, la commande affiche le sommaire général, les options globales et l’ordre de priorité de la configuration. Un nom inconnu est ignoré et ramène au sommaire.

aide est aussi ce que fait le CLI quand on ne lui donne rien du tout, ou quand on lui donne help ou --help. Une commande inconnue, en revanche, est une erreur :

Sortie du CLIbash

✗ Commande inconnue : « puhser ».
  Connues : connexion, lister, recuperer, pousser, suivre, publier. `aide` pour le détail.

#Ce qui vaut pour toutes les commandes

Aucune trace de pile ne sort du CLI. Une phrase, le geste à faire, et un code de sortie 1. --verbeux rend la trace technique quand l’erreur est inattendue.
Le format est vérifié en local avant l’envoi. Un fichier hors des six dossiers, une extension refusée, un fichier au-dessus de 512 Ko ou un thème de plus de 120 fichiers sont arrêtés sur la machine, ce qui évite un aller-retour réseau pour apprendre un refus prévisible. Les mêmes bornes sont revalidées côté serveur : voir Le bac à sable.
Seuls les six dossiers du format sont parcourus, sans descendre plus bas. .git, node_modules, .DS_Store, les captures d’écran et les fichiers cachés sont hors du champ par construction, sans liste d’exclusion à tenir à jour.

Chaque message d’échec est repris, avec sa cause, sur Erreurs.

#Commandes

#Options globales

#connexion

#lister

#recuperer

#pousser

#Les fichiers orphelins

#Créer un thème avec --nouveau

#suivre

#publier

#aide

#Ce qui vaut pour toutes les commandes

#`connexion`

#`lister`

#`recuperer`

#`pousser`

#Créer un thème avec `--nouveau`

#`suivre`

#`publier`

#`aide`