CLI

La commande chapterjs est fournie avec le paquet chapterjs. Les projets créés avec create chapterjs la lancent par leurs scripts (dev, build, start, test, postinstall).

Usage: chapterjs <command>

Commands:
  dev     Run your bot on your dev server and reload it when you save a file
  build   Check your bot and prepare it for production
  start   Run for everyone the bot that was built
  test    Check your bot without Discord: every file once, then your scenarios
  sync    Write the types of your project (dev does it too)

Options of start:
  --processes <n>   How many processes to use (by default: as many as the
                    size of your bot needs)

Comment utiliser chaque commande est dans le guide : chapterjs dev, chapterjs build, chapterjs start, chapterjs test, Déployer. Ce que veut dire chaque message est dans Dépannage.

Commandes

Chaque commande tourne dans le dossier du projet : celui qui contient package.json et src/. Sans src/, dev, build et test s’arrêtent avec ✗ There is no src folder here.

`chapterjs dev`

Fait tourner le bot du dossier courant sur le serveur de test de DEV_GUILD_ID, et recharge chaque fichier de src/ quand il est enregistré. Tourne jusqu’à ce qu’on l’arrête.

Étape	Ce qui se passe
`.env`	`BOT_TOKEN` et `DEV_GUILD_ID` sont lus et vérifiés, et `REDIS_URL` et `REDIS_PASSWORD` quand ils sont là. Chaque problème est affiché, puis la commande s’arrête.
Types	`.chapterjs/` est écrit, comme avec `chapterjs sync`.
Fichiers	Chaque fichier de `src/` est chargé, et ce qu’ils exportent avec `command()`, `event()`, `button()`… est lu. Un fichier ou une déclaration cassés sont signalés et mis de côté.
Redis	Quand un store dit `storage: 'redis'`, Redis doit répondre : sinon la raison est affichée et la commande s’arrête. Chaque clé écrite depuis `dev` commence par `dev:`.
Token	Vérifié auprès de Discord.
Serveur de test	Le bot doit y être : sinon un lien d’invitation est affiché et, dans un terminal, la commande attend.
Intents privilégiés	Ceux dont les fichiers ont besoin doivent être activés : sinon les fichiers et le lien sont affichés et, dans un terminal, la commande attend.
Connexion	Au serveur de test uniquement. Ce qui se passe dans les autres serveurs et en messages privés est écarté, et les intents qui ne servent qu’aux messages privés ne sont pas demandés.
Commandes	Enregistrées sur le serveur de test, seulement quand elles ont changé depuis la dernière fois, sans celles que la production affiche déjà telles que déclarées. Enregistrées à nouveau après un rechargement qui les a changées.
Nouvelle version	npm est interrogé, au plus une fois par jour, pour savoir si un `chapterjs` plus récent est publié : si oui, un `ℹ` donne la commande à lancer, avec le gestionnaire de paquets du projet (son lockfile, sinon celui qui a lancé la commande, sinon npm). Sans réponse en 5 secondes, rien n’est dit.
Rechargement	À chaque enregistrement dans `src/` : les fichiers sont rechargés, un fichier qui échoue garde sa dernière version qui fonctionnait, le bot se reconnecte quand les fichiers ont besoin de nouveaux intents.
Arrêt	`Ctrl+C` ou `SIGTERM` : la session est fermée et le bot passe hors ligne immédiatement. Un second arrêt sort sans attendre.

Ne prend aucune option.

`chapterjs build`

Vérifie le projet et le compile dans .chapterjs/build/. N’a pas besoin de token et n’envoie rien à Discord.

Étape	Ce qui se passe
Types	`.chapterjs/` est écrit, puis `node_modules/.bin/tsc -b` tourne quand il existe et que le projet a un `tsconfig.json`. Une erreur de type arrête la compilation. Sans TypeScript, la compilation le dit et continue.
Fichiers	La compilation précédente est supprimée. Chaque fichier de `src/` est chargé, et ce qu’il déclare est lu. Un fichier ou une déclaration cassés arrêtent la compilation.
Compilation	Chaque fichier de `src/`, avec ce qu’il importe, est regroupé dans `.chapterjs/build/bot.js` (ESM, Node 24, paquets laissés dans `node_modules`, espaces et syntaxe minifiés, noms gardés) avec `bot.js.map` à côté (sans les sources).
Vérification	Le fichier compilé est chargé une fois et chaque fichier est vérifié à nouveau.
Enregistrement	`.chapterjs/build/build.json` : la version de `chapterjs`, une empreinte de `src/`, si les fichiers rejoignent des salons vocaux.

Une compilation qui échoue ne laisse aucun .chapterjs/build/ derrière elle. Ne prend aucune option.

`chapterjs start`

Fait tourner la compilation pour tout le monde. Tourne jusqu’à ce qu’on l’arrête.

chapterjs start [--processes <n>]

Étape	Ce qui se passe
`.env`	`BOT_TOKEN` est lu et vérifié ; `DEV_GUILD_ID`, `REDIS_URL` et `REDIS_PASSWORD` sont lus quand ils sont là.
Compilation	`.chapterjs/build/` doit exister et avoir été faite par la même version de `chapterjs`. Quand `src/` est là et a changé depuis la compilation, un `⚠` le dit et la compilation tourne quand même.
Fichiers	Chargés depuis la compilation, jamais depuis `src/`.
Redis	Quand un store dit `storage: 'redis'`, Redis doit répondre. Chaque processus l’atteint lui-même.
Token et intents privilégiés	Vérifiés une fois. Un problème est une erreur : rien n’attend.
Commandes	Enregistrées pour tout le monde, seulement quand elles ont changé depuis le dernier démarrage depuis ce dossier.
Sessions	Discord est interrogé sur le nombre de shards dont le bot a besoin et le nombre de sessions qu’il peut encore démarrer aujourd’hui. Pas assez de sessions restantes arrête la commande.
Processus	Un processus pour 4 shards, jamais plus que la machine n’a de processeurs, jamais plus que les shards, ou ce que demande `--processes`. Avec plusieurs, le processus que vous avez lancé démarre les autres, préfixe leurs lignes de `[n]` , relance celui qui s’arrête tout seul et les arrête tous ensemble.
Connexion	À chaque serveur, sauf celui de `DEV_GUILD_ID` quand il est réglé. Les messages privés sont gérés.
Arrêt	`Ctrl+C` ou `SIGTERM` : chaque processus ferme sa session et le bot passe hors ligne immédiatement.

integer

Combien de processus font tourner le bot : un nombre entier de 1 ou plus, écrit --processes 4 ou --processes=4. Plafonné au nombre de shards, avec un ℹ qui le dit. Toute autre chose après start arrête la commande avec ✗ chapterjs start takes one option: ....

`chapterjs test`

Vérifie le bot contre un Discord en mémoire. N’a pas besoin de token et n’envoie rien à Discord.

Étape	Ce qui se passe
Types	`.chapterjs/` est écrit, comme `chapterjs sync`. Les types ne sont pas vérifiés : `chapterjs build` et le script `typecheck` le font.
Fichiers	Chaque fichier de `src/` est chargé, et ce qu’il déclare est lu. Un fichier ou une déclaration cassés arrêtent la commande : `✗ This file can't run, so your bot was not tested.` Un projet qui ne déclare rien s’arrête avec `ℹ Nothing to run yet`.
Vérifications	Dans un serveur en mémoire où le bot est admin : chaque commande est utilisée avec toutes ses options, avec les obligatoires seulement, et une fois par valeur difficile ; chaque bouton, menu et formulaire avec ses données et des données difficiles ; chaque événement une fois ; chaque tâche une fois. Pour chaque chose d’un fichier qui a échoué, `✗ Checked src/ping.ts: command /ping failed in 1 of 8 cases` suivi d’une ligne par cas raté, avec le fichier et la ligne de ce qui a lancé une erreur, puis ce que les fichiers ont imprimé pendant ce temps. Les fichiers qui ont réussi tiennent sur une ligne à la fin : `✓ Checked every file once: 7 checks in 2 files` (ou `✓ Checked the other 2 files once: 7 checks` quand l’un a échoué) ; ce qui a été vérifié dedans n’est pas listé, ni ce qu’ils ont imprimé. Dans un terminal, le fichier en cours s’affiche d’abord (`↻ Checking src/ping.ts`, puis une ligne `→` par chose et cas essayés), et s’efface une fois fini. Un événement que le serveur ne sait pas encore provoquer est listé dans un `ℹ`.
Scénarios	Chaque fichier `.test.ts` et `.spec.ts` de `src/` est chargé (jamais par le bot), et ce qu’il exporte fait avec `scenario()` tourne, chacun sur un serveur neuf avec des stores vides. Une ligne par fichier de test : `✓ Tested src/file.test.ts`, ou, pour chaque scénario qui a échoué, `✗ Tested src/file.test.ts: "label" failed` suivi du fichier, de la ligne et de la raison, puis ce que les fichiers ont imprimé pendant ce temps. Un scénario qui prend plus de 10 secondes échoue. Un fichier de test qui ne déclare aucun scénario est un `⚠`.
Bilan	`✓ 7 checks and 2 scenarios passed`, ou `✗ 1 of 7 checks and 1 of 2 scenarios failed`.

Ne prend aucune option. Les stores gardent leurs données en mémoire : le dossier data/ du projet n’est jamais touché.

`chapterjs sync`

Écrit le dossier .chapterjs/ du projet : ce que le projet ajoute aux types de chapterjs (les fichiers de public/, ses langues et ses commandes, trouvés en lisant les fichiers sans les exécuter) et le tsconfig.json du seul projet TypeScript qui couvre src/. Affiche ✓ Types written to .chapterjs/. N’a pas besoin de token. dev et build le font aussi au démarrage ; les modèles le lancent en postinstall. Seuls les fichiers dont le contenu a changé sont écrits ; ce qu’écrivait une ancienne version est retiré. .chapterjs/cache/ et .chapterjs/build/ sont laissés tranquilles.

`chapterjs --version`

Affiche la version du paquet. -v fonctionne aussi.

`chapterjs --help`

Affiche l’aide ci-dessus. -h et aucune commande du tout font la même chose. Tout autre mot est une erreur : ✗ "…" is not a command., suivi de l’aide.

Environnement

`.env`

dev et start lisent le fichier .env du dossier du projet, quand il y en a un, puis le vrai environnement : une variable réglée dans l’environnement l’emporte sur le fichier. Les espaces autour des valeurs sont retirés.

string

requis

Le token du bot, depuis la page Bot de l’application dans le Developer Portal. Un préfixe Bot est retiré. Refusé quand il est vide, quand c’est une valeur d’exemple restée en place (your-token-here, xxx, todo, changeme, <...>…) ou quand il contient un espace.

string

L’identifiant du serveur de test : 17 à 20 chiffres. Obligatoire pour dev, qui ne fait tourner le bot que sur ce serveur. Facultatif pour start, qui ignore alors ce serveur, pour que dev et start puissent partager un token sans répondre deux fois à la même chose. Refusé quand ce n’est pas un identifiant.

string

L’adresse du Redis qu’utilisent les stores déclarés avec storage: 'redis' : redis://hôte:port, rediss:// pour une connexion TLS, /1 à la fin pour une base autre que la première, un utilisateur et un mot de passe devant l’hôte quand il y en a (redis://user:password@host:6379). Nécessaire seulement quand un store dit storage: 'redis' ; réglée sans store de ce genre, rien n’est connecté. Refusée quand ce n’est pas une adresse de cette forme. Voir Stockage.

string

Le mot de passe de ce Redis, quand il n’est pas dans REDIS_URL (ou pour remplacer celui qui y est). Refusé quand REDIS_URL n’est pas réglée.

Sans fichier .env, dev s’arrête avec ✗ There is no .env file in this folder. quand aucune des deux valeurs n’est dans l’environnement, et start avec ✗ BOT_TOKEN is not set. quand le token n’y est pas.

Autres variables

string

Réglez-la sur n’importe quoi pour afficher les symboles sans couleur. Les couleurs ne sont de toute façon utilisées que quand la sortie est un terminal.

string

Lue par Node lui-même. --max-old-space-size=<MB> augmente la mémoire que le bot peut utiliser : voir Mémoire.

Le fait qu’une personne regarde (dev attend une correction au lieu de s’arrêter) est décidé par le terminal : l’entrée et la sortie doivent toutes deux être un terminal.

Codes de sortie

Code	Commande	Quand
`0`	toutes	Arrêtée par `Ctrl+C` ou `SIGTERM`, ou terminée : une compilation réussie, un test qui a réussi, `sync`, `--version`, `--help`.
`1`	`dev`, `start`	Un problème avant la connexion (une valeur de `.env`, le token, le serveur de test ou un intent quand elle n’attend pas, pas de compilation, pas assez de sessions), ou Discord a refusé le bot pour de bon pendant qu’il tournait. Aussi un second `Ctrl+C`.
`1`	`build`	Des erreurs de type, un fichier qui ne peut pas tourner, pas être compilé ou pas tourner une fois compilé.
`1`	`test`	Un fichier qui ne peut pas tourner, une vérification ou un scénario qui a échoué.
`1`	toutes	Une commande inconnue, ou `start` avec autre chose que `--processes <n>`.
`78`	un processus démarré par `start`	Discord a refusé le bot dans ce processus : celui que vous avez lancé arrête alors chaque processus et sort avec `1`.

Symboles

Chaque ligne affichée par le CLI commence par l’un de cinq symboles. Les lignes qui suivent la première d’un message sont indentées sous elle.

Symbole	Signification
`✓`	Quelque chose a fonctionné
`ℹ`	Quelque chose à savoir
`↻`	Un rechargement ou une reconnexion
`⚠`	Quelque chose à regarder, qui n’arrête pas le bot
`✗`	Quelque chose a échoué : ce qui s’est passé, puis quoi faire

Une erreur dans un fichier du projet est préfixée par son chemin, et sa ligne quand elle est connue : ✗ src/commands/ping.ts:4 …. Avec plusieurs processus, chaque ligne d’un processus commence par son numéro : [2] ✓ ….

`.chapterjs/`

Ce que le CLI garde dans le projet, ignoré par git :

Chemin	Écrit par	Ce que c’est
`types/project.d.ts`, `tsconfig.json`	`sync`, `dev`, `build`	Ce que le projet ajoute aux types de `chapterjs`, et le seul projet TypeScript qui couvre `src/`.
`cache/commands.json`, `cache/commands.global.json`	`dev`, `start`	Une empreinte des dernières commandes enregistrées sur le serveur de test et pour tout le monde, pour que rien ne soit envoyé quand elles n’ont pas changé.
`cache/update.json`	`dev`	La dernière version publiée par npm, et quand il a été interrogé : il l’est à nouveau un jour plus tard.
`build/bot.js`, `build/bot.js.map`, `build/build.json`	`build`	Le bot compilé, sa correspondance vers `src/`, et ce dont la compilation était faite.

Le dossier peut être supprimé à tout moment : sync réécrit les types, le prochain dev ou start enregistre à nouveau les commandes, et build fait une nouvelle compilation.

Référence

Vos fichiers

Structures

Types

CLI

Commandes

`chapterjs dev`

`chapterjs build`

`chapterjs start`

`chapterjs test`

`chapterjs sync`

`chapterjs --version`

`chapterjs --help`

Environnement

`.env`

Autres variables

Codes de sortie

Symboles

`.chapterjs/`