> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Chaque commande de chapterjs, ce qu’elle lit dans l’environnement, ses codes de sortie et les symboles de ses messages

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

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
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)
```

> [!NOTE]
>
> Comment utiliser chaque commande est dans le guide : [chapterjs dev](https://www.chapterjs.org/fr/run/dev.md), [chapterjs build](https://www.chapterjs.org/fr/run/build.md), [chapterjs start](https://www.chapterjs.org/fr/run/start.md), [chapterjs test](https://www.chapterjs.org/fr/testing.md), [Déployer](https://www.chapterjs.org/fr/run/deploy.md). Ce que veut dire chaque message est dans [Dépannage](https://www.chapterjs.org/fr/run/troubleshooting.md).

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

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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. |

**--processes** `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.

**BOT\_TOKEN** `string` *required*

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.

**DEV\_GUILD\_ID** `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.

**REDIS\_URL** `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](https://www.chapterjs.org/fr/storage.md#dans-redis).

**REDIS\_PASSWORD** `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

**NO\_COLOR** `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.

**NODE\_OPTIONS** `string`

Lue par Node lui-même. `--max-old-space-size=<MB>` augmente la mémoire que le bot peut utiliser : voir [Mémoire](https://www.chapterjs.org/fr/memory.md).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.