#Installation
Le CLI n’a aucune dépendance : il n’importe que des modules node:. Il n’y a
donc rien à télécharger, et rien à tenir à jour séparément du dépôt.
Trois façons de l’appeler, et elles exécutent exactement le même code.
Le paquet webcosa est servi par la plateforme elle-même, catalogue de thèmes
compris, et il est refait à chaque mise en ligne. C'est la forme à retenir hors
du dépôt — sur le poste d'une partenaire, par exemple :
npm i -g https://dev.webcosa.com/cli/webcosa.tgzwebcosa connexionPour mettre à jour : la même commande.
Un lien symbolique, une fois, depuis la racine du dépôt :
npm linkLa commande s’appelle ensuite webcosa, depuis n’importe quel dossier :
webcosa aidewebcosa — le CLI de Webcosa
webcosa <groupe> <commande> [options]La forme historique, sans installation du tout. Elle ne couvre que le groupe
theme, et il faut être dans le dépôt :
node scripts/theme.mjs aidewebcosa theme — les thèmes d'un site Webcosa
node scripts/theme.mjs <commande> [options]Si l’une de ces commandes affiche l’aide, vous êtes prêt. Il reste à enregistrer une clé.
Les deux formes ne divergeront pas. scripts/theme.mjs est à la fois un
module que webcosa importe et un programme qu’on peut lancer seul : la
séparation tient en une garde sur process.argv[1], et les commandes, les
options et les messages sont les mêmes objets des deux côtés.
Le groupe site, lui, n’existe que sous webcosa — il n’a pas de forme
historique à préserver.
#Prérequis
Node.js≥ 20.13requisC’est le seul prérequis. Node 22 LTS ou 24 est le choix recommandé : c’est ce sur quoi le CLI est développé et vérifié.
Un éditeur de texteau choixAucune extension n’est nécessaire. La coloration Liquid de n’importe quel éditeur convient — le format est celui de Shopify, donc les greffons existants fonctionnent.
Vérifiez ce que vous avez :
node --versionv24.12.0D’où vient ce plancher de 20.13. Le dépôt ne fixe aucune version : il n’y a
ni champ engines dans package.json, ni .nvmrc. Le plancher est donc celui
des API que le script utilise réellement, et deux le fixent :
parseArgsdenode:util, qui analyse la ligne de commande — stable depuis Node 20 ;fs.watchen moderecursive, dont vit la commandesuivre— disponible de longue date sur macOS et Windows, mais sur Linux seulement depuis 20.13.0. En dessous,suivrene voit passer aucune sauvegarde sur une machine Linux, sans lever la moindre erreur. C’est exactement le genre de panne qu’on met une heure à comprendre.
Sur Node 18, fetch existe mais reste marqué expérimental et écrit un
avertissement à chaque appel. Le CLI fonctionne, la sortie devient illisible.
#Où vit le code
lyvora-cms/
├── scripts/
│ ├── webcosa.mjs ← le point d'entrée, celui de `bin`
│ ├── theme.mjs ← le groupe theme : module ET programme
│ └── lib/
│ ├── cli-noyau.mjs ← affichage, saisie, configuration, appels
│ ├── site-commandes.mjs ← le groupe site
│ ├── theme-controles.mjs ← les contrôles locaux de `verifier`
│ └── archive-zip.mjs ← le .zip d'`empaqueter`
├── themes/ ← les thèmes D'ORIGINE, pas un dossier de travail
│ ├── origo/
│ ├── forge/
│ └── vela/
└── src/package.json déclare "bin": { "webcosa": "./scripts/webcosa.mjs" } : c’est ce
que npm link installe.
webcosa theme listerLe dossier themes/ à la racine du dépôt n’est pas un dossier de travail. Il
contient les thèmes d’origine, compilés dans src/lib/liquid/catalogue.ts par
scripts/compiler-themes.mjs, et proposés à l’installation à tous les sites. Un
thème récupéré là finirait au catalogue sans que personne l’ait décidé.
Le CLI le détecte et vous avertit — mais il n’empêche rien :
! /Users/marc/lyvora-cms/themes/atelier est sous le `themes/` du dépôt — celui
des thèmes d'ORIGINE, compilé dans le catalogue. Préfère `--dossier=` ailleurs.Travaillez ailleurs, avec --dossier=. Faire entrer un thème au catalogue est un
geste délibéré, décrit dans Ajouter un thème au catalogue.
#L’utiliser hors du dépôt
Le CLI ne lit aucun fichier du produit, ne résout aucun alias @/ et n’a besoin
de rien d’autre que Node. Il peut donc vivre ailleurs que dans le dépôt — mais
il faut emporter le dossier scripts/ entier, pas un seul fichier :
webcosa.mjs importe theme.mjs, qui importe lib/cli-noyau.mjs,
lib/theme-controles.mjs et lib/archive-zip.mjs.
Le lien pointe sur le dépôt : une mise à jour de celui-ci met à jour la commande, sans rien recopier.
cd lyvora-cms
npm link
cd ~/themes/atelier
webcosa theme poussernpm unlink -g webcosa-cms défait le lien.
cp -R lyvora-cms/scripts ~/themes/outils/
node ~/themes/outils/webcosa.mjs aideCopier theme.mjs seul ne marche pas : il lui manquerait lib/.
# ~/.zshrc
alias webcosa='node ~/themes/outils/webcosa.mjs'
webcosa theme pousserUne copie ne se met pas à jour toute seule — c’est la raison de préférer
npm link. Le CLI recopie une partie du format des thèmes (les six dossiers, les
extensions admises, TAILLE_MAX, FICHIERS_MAX) parce qu’il tourne hors de Next
et ne peut pas lire un module TypeScript. La divergence est sans danger : le
serveur revalide tout ce qu’il reçoit, donc au pire une copie vieillie enverra
un fichier que le serveur refusera avec son propre message. Mais elle ne
vous évitera plus l’aller-retour réseau, ce qui est justement sa raison d’être.
Une copie perd aussi webcosa theme nouveau, qui lit les thèmes d’origine dans
le themes/ du dépôt — à moins d’emporter ce dossier-là aussi.
#Un dossier de thème, de zéro
Trois façons de commencer, de la plus rapide à la plus nue.
La plus rapide, et celle qui ne demande ni clé ni réseau : un thème d’origine
est copié dans un dossier neuf, avec son .webcosa.json déjà posé.
webcosa theme nouveau # la liste des thèmes d'origine
webcosa theme nouveau --depuis=origo --nom="Mon thème"Le dossier obtenu est complet et fonctionnel : webcosa theme verifier passe
dessus sans rien signaler, et webcosa theme pousser --nouveau le crée sur le
site, en brouillon.
Installez un thème d’origine depuis le CMS (Apparence → Thèmes), puis récupérez-le. À préférer quand vous reprenez un thème que le client a déjà retouché :
webcosa theme recuperer --theme=Origo --dossier=~/themes/mon-themeCréez les six dossiers, écrivez au minimum layout/theme.liquid,
config/settings_schema.json et templates/index.json, puis :
webcosa theme pousser --nouveau --nom="Mon thème" --dossier=~/themes/mon-themeLe pas à pas complet est dans Créer son premier thème.
nouveau lit les thèmes d’origine sur le disque, dans le themes/ du dépôt :
elle ne fonctionne donc que dans le dépôt ou dans une installation faite par
npm link. Aucune route d’API ne sert le contenu des thèmes du catalogue — elle
les installe sur un site, elle ne les rend pas.
#Vérifier que tout répond
L’aide s’affiche
webcosa aideSi vous obtenez
command not found: webcosa, c’est quenpm linkn’a pas été fait —node scripts/webcosa.mjs aidemarche sans lui.La clé est enregistrée
webcosa theme connexionLa commande vérifie la clé avant de l’écrire : si elle affiche le nom de votre site, l’authentification fonctionne de bout en bout.
Le site répond
webcosa theme listerid 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 jUne liste vide n’est pas une panne : c’est un site sans thème. Pars d’un thème d’origine avec
webcosa theme nouveau, ou installez-en un depuis le CMS.
--verbeux détaille chaque appel HTTP — méthode, adresse, site visé, présence
de la clé. C’est la première chose à ajouter quand une commande ne fait pas ce
qu’on croyait :
webcosa theme lister --verbeuxSi une commande échoue, la page des erreurs reprend chaque message avec sa cause et le geste à faire.

