CLI
Sommaire
- Usages principaux
- Entrées disponibles
- Exécuter du code
- REPL
- Script
- Expression et stdin
- Options globales
- Choisir l'exécuteur
- Niveaux de parsing
- Optimisations
- Modules
- Affichage
- Variables d'environnement
- Sous-commandes
- Formatter
- Linter
- Configuration
- Modules
- Cache
- Debugger
- LSP
- Complétion shell
- Commandes et plugins
- Erreurs
- Codes de sortie
La commande catnip exécute du code, ouvre la REPL et donne accès aux outils du projet.
Console basse friction : des flags comme vecteurs de trajectoire.
Usages principaux
# REPL interactive
catnip
# Script
catnip script.cat
# Expression
catnip -c "2 + 3 * 4"
# ⇒ 14
# Entrée standard
echo "10 * 2" | catnip
# ⇒ 20
Catnip est surtout conçu comme moteur DSL embarqué. Pour une application complète ou un script autonome qui grossit, Python reste généralement le meilleur host ; Catnip garde alors les règles et transformations configurables. Voir le guide d'embedding.
Entrées disponibles
Selon l'installation, catnip désigne le binaire Rust ou le console script Python fourni par pip. Les deux exécutent
les scripts et servent les sous-commandes, mais quelques options leur sont propres :
| Entrée | Options propres |
|---|---|
| Binaire Rust | --no-jit, --jit-threshold, --policy, bench, info |
| Console script (pip) | -p/--parsing, -x/--executor, -m/--module, -o/--optimize |
Quand les deux sont installés au même emplacement, la dernière installation gagne. catnip --help affiche toujours
l'interface réellement active. Les détails d'installation et d'exécution standalone sont dans RUN.
Exécuter du code
REPL
catnip
catnip repl
catnip-repl
La session conserve les variables entre deux commandes. Commandes, raccourcis et choix entre les REPL Rust et Python : voir REPL.
Script
catnip script.cat
catnip -v script.cat
catnip -- script.cat
Le séparateur -- force l'interprétation de l'argument suivant comme fichier. Il lève l'ambiguïté si un fichier porte
le nom d'une sous-commande :
catnip -- format.cat
Expression et stdin
catnip -c "x = 10; x * 2"
# ⇒ 20
cat script.cat | catnip
echo "factorial(10)" | catnip -o tco:on
Dans ces deux modes, sys.argv vaut respectivement ["-c"] et [""] — la forme que Python donne au code qui ne vient
pas d'un fichier. Voir RUN pour le mode script.
Options globales
| Option | Rôle |
|---|---|
-c, --command CODE |
Évaluer du code inline |
-p, --parsing LEVEL |
Arrêter le pipeline au niveau 0–3 |
-x, --executor vm\|ast |
Choisir la VM ou l'interpréteur AST |
-o, --optimize OPT |
Régler TCO, JIT, niveau d'optimisation ou limite mémoire |
-m, --module MODULE |
Charger un module Python |
--policy PROFILE |
Sélectionner une policy de modules nommée |
--config FILE |
Utiliser un autre catnip.toml |
--format text\|json\|repr |
Choisir le format des niveaux de parsing 1 et 2 |
--theme auto\|dark\|light |
Choisir le thème du terminal |
--no-color |
Désactiver les couleurs |
--no-cache |
Désactiver le cache de parsing et de bytecode pour cette exécution |
-q, --quiet |
Masquer le résultat final sans supprimer les effets de bord |
-v, --verbose |
Afficher les étapes du pipeline |
-V, --version |
Afficher la version |
-h, --help |
Afficher l'aide correspondant à l'entrée installée |
Choisir l'exécuteur
-x vm (défaut) ou -x ast. La variable CATNIP_EXECUTOR fait la même chose ; la casse et les espaces autour de la
valeur sont ignorés, et une valeur qu'aucun des deux ne sait lire est refusée par son nom au lieu d'être appliquée.
CATNIP_EXECUTOR=bogus arrête donc l'exécution avec un message, là où elle retombait auparavant sur la VM sans le dire.
Les deux moteurs rapportent une erreur avec le même message, la même position et le même extrait de code. Reste un écart : la pile d'appels, que seule la VM peut produire.
⇒ vm
Traceback (most recent call last):
File "script.cat", line 7, in outer
NameError: Name 'nope' is not defined
Did you mean 'open'?
2 | x + nope
| ^
⇒ ast
NameError: Name 'nope' is not defined
Did you mean 'open'?
2 | x + nope
| ^
L'écart restant vient de ce que chaque moteur sait de son exécution : la VM conserve un offset source par instruction et
la pile d'appels au moment de l'échec, l'interpréteur AST n'enregistre pas de frames. Le reste du rapport est identique
depuis la 0.1.3 ; -x ast est l'oracle de comportement, pas de présentation.
Niveaux de parsing
| Niveau | Résultat |
|---|---|
0 |
Arbre Tree-sitter brut |
1 |
IR après transformation |
2 |
IR exécutable après analyse sémantique |
3 |
Exécution et affichage du résultat, valeur par défaut |
Les niveaux 0–2 servent surtout à inspecter le langage et les optimiseurs :
catnip --parsing 1 -c "2 + 3"
catnip --parsing 2 --format json script.cat
text produit un JSON compact, json la structure serde complète et repr la représentation Python historique.
--format n'affecte que les niveaux 1 et 2.
Optimisations
-o est répétable :
catnip -o tco script.cat
catnip -o tco:off script.cat
catnip -o jit script.cat
catnip -o jit:off script.cat
catnip -o level:0 script.cat
catnip -o level:3 script.cat
catnip -o memory:4096 script.cat
Une occurrence peut aussi porter plusieurs options séparées par des virgules. Les deux écritures suivantes sont
équivalentes, et à CATNIP_OPTIMIZE=jit,level:3 :
catnip -o jit -o level:3 script.cat
catnip -o jit,level:3 script.cat
Pour tco et jit, les booléens acceptés sont on/off, true/false, 1/0 et yes/no. Le niveau
d'optimisation est un seuil : 0 désactive les passes, 1 et 2 activent les passes locales, 3 ajoute en plus le
tier inter-blocs CFG+SSA (LICM, DSE globale, GVN). Le défaut est 2 : le tier inter-blocs se demande. memory:0
désactive la garde mémoire ; la vérification RSS est disponible sous Linux. Une valeur que Catnip ne sait pas lire est
refusée avec le nom de l'option en cause et la liste de ce qu'elle accepte.
Les options CLI prennent priorité sur les pragmas du fichier. La référence des pragmas est dans PRAGMAS.
Modules
catnip -m math script.cat
catnip -m math:m script.cat
catnip -m io:! script.cat
catnip --policy sandbox script.cat
-m name:alias renomme le namespace et -m name:! injecte les exports dans les globals. Pour la résolution des
modules, import(), les imports relatifs et les policies, voir MODULE_LOADING.
Affichage
catnip --theme light script.cat
catnip --no-color script.cat
catnip -q script.cat
-q masque seulement le résultat final. Les appels à print() et les autres effets de bord sont toujours exécutés.
NO_COLOR désactive aussi les couleurs.
Variables d'environnement
| Variable | Rôle |
|---|---|
CATNIP_CONFIG |
Fichier de configuration alternatif |
CATNIP_CACHE |
Activation du cache |
CATNIP_OPTIMIZE |
Options au même format que -o, séparées par des virgules |
CATNIP_EXECUTOR |
Exécuteur vm ou ast |
CATNIP_PATH |
Répertoires supplémentaires pour import() |
CATNIP_THEME |
Thème auto, dark ou light |
CATNIP_QUIET |
Masquage du résultat final |
NO_COLOR |
Désactivation standard des couleurs |
XDG_CONFIG_HOME |
Racine de catnip/catnip.toml |
XDG_STATE_HOME |
Racine de l'historique REPL |
XDG_CACHE_HOME |
Racine des caches |
La priorité est :
défauts ⇒ fichier de configuration ⇒ environnement ⇒ CLI
La liste complète des clés, les overrides par mode et l'inspection des sources sont dans CONFIG.
Sous-commandes
La CLI charge ses sous-commandes à la demande. catnip commands affiche celles qui sont disponibles dans l'installation
courante.
| Commande | Synopsis | Référence |
|---|---|---|
format |
Formater ou vérifier des fichiers | Formatter |
lint |
Analyser syntaxe, style et sémantique | Linter |
debug |
Déboguer avec breakpoints et stepping | Debugger |
repl |
Ouvrir explicitement la REPL | REPL |
config |
Lire ou modifier catnip.toml |
Configuration |
module |
Inspecter les policies de modules | Module loading |
cache |
Inspecter, élaguer ou vider le cache | Configuration |
lsp |
Lancer le serveur LSP sur stdio | Cette page |
completion |
Générer la complétion Bash, Zsh ou Fish | Cette page |
commands |
Lister les commandes disponibles | Cette page |
plugins |
Inspecter les entry points CLI | Cette page |
extensions |
Inspecter les extensions Catnip | Étendre le contexte |
new-lib |
Créer le squelette d'un module stdlib | Aide de la commande |
info |
Inspecter le runtime Rust | Binaire Rust uniquement |
bench |
Mesurer le pipeline Rust | Binaire Rust uniquement |
Formatter
catnip format script.cat
catnip format -i src/
catnip format --check src/
catnip format --diff script.cat
echo "x=1+2" | catnip format --stdin
Les options de style viennent de [format] dans catnip.toml et peuvent être surchargées en CLI : --indent-size et
--line-length remplacent les valeurs de la config, --align et --no-align forcent l'alignement en colonne dans un
sens ou dans l'autre. Sans ces options, la config s'applique.
Linter
catnip lint script.cat
catnip lint -l syntax script.cat
catnip lint --deep --strict src/
catnip lint --disable W401,I200 script.cat
catnip lint --enable W401 script.cat
--disable ajoute des codes à ceux du fichier de configuration ; --enable les réactive. Les diagnostics, métriques et
commentaires # noqa sont documentés dans le guide du linter.
Configuration
catnip config show
catnip config show --debug
catnip config get jit
catnip config set jit true
catnip config path
show --debug indique la source de chaque valeur. Le format du fichier n'est défini qu'une fois, dans
CONFIG.
Modules
catnip module list-profiles
catnip module check sandbox os math json
list-profiles liste les policies nommées. check affiche les modules autorisés ou refusés sous un profil.
Cache
catnip cache stats
catnip cache prune
catnip cache prune --dry-run
catnip cache clear
prune retire les entrées expirées, puis applique la limite de taille en supprimant les entrées les moins récemment
utilisées. clear vide le cache.
Debugger
catnip debug -b 5 -b 12 script.cat
catnip debug -c "x = 10; y = x * 2" -b 1
Au point d'arrêt, les commandes principales sont continue, step, next, out, print, vars, list,
backtrace, repl et quit. Le détail est dans Debugger.
LSP
catnip lsp
Le serveur communique en JSON-RPC sur stdio et expose diagnostics, formatage et renommage scope-aware. Le binaire
catnip-lsp doit être installé.
Le formatage porte sur le document entier, et un document dont la syntaxe est refusée ne renvoie aucune modification : un « formater à l'enregistrement » sur un fichier en cours d'écriture le laisse tel quel. Les diagnostics, eux, continuent de signaler l'erreur.
Les diagnostics honorent la configuration lint résolue comme pour catnip lint : CATNIP_CONFIG (une valeur vide
compte comme absente), sinon le catnip.toml du répertoire de configuration XDG. Les codes listés dans [lint] disable
ne sont pas publiés. La configuration est lue au démarrage du serveur : un changement demande un redémarrage. --deep
et --check-names restent des options du CLI, sans équivalent LSP.
Complétion shell
# Bash
eval "$(catnip completion bash)"
# Zsh
eval "$(catnip completion zsh)"
# Fish
catnip completion fish | source
Pour une installation persistante, rediriger la sortie vers le fichier de configuration du shell.
Commandes et plugins
catnip commands
catnip commands --no-resolve
catnip plugins
catnip plugins --entrypoints
catnip plugins --check
Les packages Python peuvent ajouter une commande via le groupe d'entry points catnip.commands :
[project.entry-points."catnip.commands"]
mycommand = "my_plugin:mycommand"
Erreurs
Les erreurs indiquent la ligne, la colonne et le fragment source. Une erreur dans la REPL ne ferme pas la session.
Codes de sortie
| Code | Signification |
|---|---|
0 |
Succès |
1 |
Erreur de fichier, syntaxe, exécution, formatage ou lint |
| au choix | Code demandé explicitement par sys.exit(code) |
format --check et lint retournent 1 quand leur vérification échoue :
catnip format --check src/ || exit 1
catnip lint --deep --strict src/ || exit 1
Une CLI documentée deux fois finit par avoir deux passés.
catnip --helpreste le présent administratif.