Référence CLI

Référence complète pour l'interface de ligne de commande bext.

Voir docs/platform/02-cli.md dans le référentiel bext pour les spécifications complètes.

Conseil

Exécutez bext-server check avant de passer en production : il valide votre configuration, confirme que les ports sont accessibles et vérifie les chemins de certificat TLS sans démarrer le serveur.

Commandes principales#

bash

bext-server run [dir]                    # Run an app (auto-detect framework, build, serve)
bext-server dev [dir]                    # Dev mode with file watching and hot reload
bext-server build [dir]                  # Build the SSR bundle for production
bext-server serve                        # Start the multi-app platform server

Déploiement#

bash

bext-server deploy <dir> --app <name>    # Deploy an app (build + swap)

Gestion des applications#

bash

bext-server apps list                    # List registered apps
bext-server apps add <name>              # Register a new app
bext-server apps remove <name>           # Unregister an app
bext-server apps info <name>             # Show app details

Gestion du cache#

bash

bext-server cache stats                  # Cache hit rates, sizes, per-app breakdown
bext-server cache purge --app <name>     # Purge app cache
bext-server cache purge --tag <tag>      # Purge by tag
bext-server cache warm <url-list>        # Pre-warm cache from URL list

Gestion des plugins#

bash

bext-server plugins list                 # List installed plugins
bext-server plugins install <path.wasm>  # Install a WASM plugin
bext-server plugins remove <name>        # Remove a plugin
bext-server plugins inspect <path.wasm>  # Show manifest, permissions, size

Inspection et diagnostic#

bash

bext-server routes [dir]                 # Print route table for an app directory
bext-server config validate [file]       # Validate config file
bext-server config show                  # Show loaded configuration
bext-server health                       # Platform health check
bext-server metrics                      # Current metrics snapshot
bext-server ps                           # Running apps, worker count, memory usage
bext-server check                        # Pre-flight diagnostics (config, ports, TLS, paths)

Visibilité des points de terminaison#

bash

bext-server config endpoints list        # List all built-in URLs by category
bext-server config endpoints show        # Show which endpoint groups are enabled
bext-server config endpoints enable <g>  # Print TOML to enable a group
bext-server config endpoints disable <g> # Print TOML to disable a group

Groupes : health, metrics, api, obs, admin. Voir Points de terminaison et informations d'identification pour plus de détails.

Gestion des informations d'identification#

bash

bext-server config credentials create    # Create admin user (argon2id hash)
bext-server config credentials hash      # Hash a password and print the hash

Créer des drapeaux :

Drapeau	Défaut	Description
`--username`	(requis)	Nom d'utilisateur administrateur
`--role`	`super_admin`	`super_admin`, `tenant_admin` ou `viewer`
`--password`	(interactif)	Mot de passe (invite masquée en cas d'omission)
`--tenant-id`	(aucun)	Requis pour le rôle `tenant_admin`
`--json`	FAUX	Sortie en JSON au lieu de TOML

Voir Points de terminaison et informations d'identification pour plus de détails.

Moteur de flux#

bash

bext-server flows list                   # List active flows
bext-server flows inspect <id>           # Show flow steps and status
bext-server flows cancel <id>            # Cancel a running flow
bext-server flows gc                     # Force garbage collection

Gestion des sauvegardes#

bash

bext-server backup create                # Create a backup to local, S3, or R2
bext-server backup list                  # List available backups
bext-server backup restore <backup-id>   # Restore from a backup

Indicateurs de stockage (s'appliquent à toutes les sous-commandes de sauvegarde) :

bash

--provider <local|s3|r2>     # Storage backend (env: BEXT_STORAGE_PROVIDER)
--bucket <name>              # S3/R2 bucket (env: BEXT_STORAGE_BUCKET)
--region <region>            # AWS region (env: BEXT_STORAGE_REGION)
--endpoint <url>             # Custom endpoint for R2/MinIO (env: BEXT_STORAGE_ENDPOINT)
--prefix <prefix>            # Key prefix for all objects

Créer des indicateurs spécifiques :

bash

--data-dir <path>            # Database directory (default: .bext/data)
--blob-dir <path>            # Blob directory (default: .bext/blobs)
--no-blobs                   # Skip blob files
--no-databases               # Skip databases
--max-size-mb <mb>           # Maximum backup size (0 = unlimited)

Tous les indicateurs reviennent à la section [storage] dans bext.config.toml.

Authentification#

`bext login`#

Connectez-vous à bext cloud via OAuth2. Ouvre votre navigateur pour l'authentification, puis stocke les informations d'identification localement.

bash

bext login [--cloud-url URL]

Drapeau	Défaut	Description
`--cloud-url`	`https://cloud.bext.dev`	URL bext cloud

Les informations d'identification sont enregistrées dans ~/.bext/credentials.json (mode 0600). Après la connexion, toutes les commandes cloud ( nginx sync-cloud, nginx diff, etc.) utilisent automatiquement votre identité.

`bext logout`#

Supprimez les informations d'identification stockées.

bash

bext logout

`bext whoami`#

Afficher l'état d'authentification actuel et vérifier la validité du jeton.

bash

bext whoami [--cloud-url URL]

Synchronisation cloud nginx#

bash

bext-server nginx list                   # List vhosts with stable IDs
bext-server nginx diff                   # Compare nginx config vs cloud projects
bext-server nginx sync-cloud             # Push vhosts to bext cloud as projects
bext-server nginx remove-cloud --only <ids>  # Remove cloud projects by vhost ID

Chaque hôte virtuel obtient un identifiant hexadécimal stable à 4 caractères (dérivé de sa liste de domaines). Utilisez list pour voir les identifiants, puis sync-cloud --only <id>,<id> pour synchroniser sélectivement.

nginx list montre une colonne framework avec une détection précise (par exemple wordpress, laravel, static ). Lorsque --json est utilisé, la sortie inclut des champs étendus : php_fpm_socket, php_version, ssl_cert_path et ssl_expires_at.

nginx sync-cloud envoie des métadonnées complètes vers le cloud : chemins racine, sockets PHP-FPM, version PHP, expiration du certificat SSL et type d'action.

bash

# Full workflow
bext-server nginx list                                  # See what's in nginx
bext-server nginx diff --cloud-api-key $KEY             # See what's different
bext-server nginx sync-cloud --only a282,5427           # Push selected vhosts
bext-server nginx remove-cloud --only c02c              # Clean up stale ones

Drapeaux :

bash

--nginx-config <path>        # Path to nginx.conf (auto-detected if omitted)
--cloud-url <url>            # Cloud API URL (default: http://localhost:3025, env: BEXT_CLOUD_URL)
--cloud-api-key <key>        # API key (optional — if not provided, uses credentials
                             # from `bext login`; falls back to BEXT_CLOUD_API_KEY env var)
--dry-run                    # Preview without making changes
--only <id>,<id>             # Filter by vhost IDs (from `nginx list`)
--json                       # JSON output (list and diff)

Diagnostic#

`bext diagnose`#

Connectez-vous à une instance bext en cours d'exécution et affichez les diagnostics en direct. Affiche l'état de santé, les hôtes virtuels, les travailleurs de rendu, le cache, la licence et les fonctionnalités compilées.

bash

bext-server diagnose --pass <admin-password>

Sortir:

code

  bext diagnose v0.1.2

  Status:  ok (97 vhosts, 1680 requests, 4 connections)
  Features: v8, tls, redis, realtime, waf, php, nginx-compat
  Uptime:  4d 12h 33m (PID 169009)
  Workers: 4 (mode: masquerade)
  ISR:     1024 entries
  Requests: 48201 total, 0 errors
  License: enterprise (expires: 2027-04-04, 361 days remaining)

Pour la consommation LLM/script :

bash

bext-server diagnose --pass <password> --format json

Drapeau	Défaut	Description
`--pass`	(requis)	Mot de passe administrateur pour l'authentification
`--user`	`admin`	Nom d'utilisateur administrateur
`--url`	`http://127.0.0.1:80`	URL de l'API d'administration
`--format`	`human`	Format de sortie : `human` ou `json`

`bext logs`#

Suivez les journaux de requêtes récentes d’une instance bext en cours d’exécution avec filtrage.

bash

bext-server logs --pass <admin-password>

Sortir:

code

  200 / 12ms hit 2026-04-08T10:30:01Z
  200 /features 45ms miss 2026-04-08T10:30:02Z
  404 /nonexistent 1ms - 2026-04-08T10:30:03Z
  500 /api/broken 234ms - 2026-04-08T10:30:04Z
  50 entries

Filtrer par code d'état ou chemin :

bash

bext-server logs --pass <pw> --status 5xx         # Only server errors
bext-server logs --pass <pw> --status 404          # Only 404s
bext-server logs --pass <pw> --path /api           # Only API requests
bext-server logs --pass <pw> --count 100           # Show 100 entries
bext-server logs --pass <pw> --format json         # JSON for LLMs

Drapeau	Défaut	Description
`--pass`	(requis)	Mot de passe administrateur
`--user`	`admin`	Nom d'utilisateur administrateur
`--count`	`50`	Nombre d'entrées
`--status`	(tous)	Filtre : code exact ( `500` ) ou plage ( `5xx`, `4xx` )
`--path`	(tous)	Filtrer par préfixe de chemin
`--format`	`human`	`human` ou `json`
`--url`	`http://127.0.0.1:80`	URL de l'API d'administration

`bext llm-hints`#

Imprimez des informations structurées sur bext pour les assistants AI/LLM. Comprend le schéma de configuration, les commandes disponibles, les moteurs de rendu, la détection du framework et les fonctionnalités compilées.

bash

bext-server llm-hints

Cela génère un document markdown que les assistants IA peuvent utiliser pour comprendre les capacités et la configuration de bext sans lire le code source.

Expérience du développeur#

`bext explain`#

Recherchez n’importe quel code d’erreur bext et obtenez une description complète avec des exemples et les étapes suivantes.

bash

bext explain                             # List all known error codes
bext explain E_CONFIG_PARSE              # Full explanation with examples
bext explain E_CACHE --json              # JSON output for CI
bext explain config_parse                # Works without the E_ prefix

Les codes d'erreur suivent le modèle E_<AREA>_<WHAT>. Domaines : configuration, plug-in, construction, rendu, cache, TLS, WAF, proxy, authentification, exécution, déploiement, mise à niveau, secrets, réseau. La correspondance floue suggère le code le plus proche lorsqu'aucune correspondance exacte n'est trouvée.

Voir Codes d'erreur pour le registre complet.

`bext test`#

Exécuteur de tests unifié : découvre et exécute toutes les suites de tests du projet.

bash

bext test                                # Run all discovered suites
bext test --kind cargo                   # Only Rust crate tests
bext test --kind node                    # Only Node/Bun package tests
bext test --filter bext-dx               # Filter by suite name
bext test --dry-run                      # List suites without running
bext test --json                         # Machine-readable report

Découverte : caisses cargo test, binaires de harnais de plugins, tests de fumée de site ( test.sh ), tests de packages Node/Bun, harnais E2E du navigateur. Le rapport affiche les réussites/échecs par suite avec les durées.

Drapeau	Défaut	Description
`--filter`	(tous)	Correspondance de sous-chaîne sur le nom de la suite
`--kind`	(tous)	`cargo`, `node`, `harness`, `browser`, `ecosystem`, `smoke`
`--watch`	FAUX	Réexécutez les suites concernées lors du changement de fichier
`--dry-run`	FAUX	Liste des suites découvertes sans exécuter
`--json`	FAUX	Rapport JSON

`bext scaffold`#

Ajoutez des fonctionnalités communes à un site existant à partir d'un catalogue organisé.

bash

bext scaffold list                       # Show all available features
bext scaffold add auth-jwt               # Add JWT authentication
bext scaffold add cron                   # Add cron jobs
bext scaffold add rate-limit --dry-run   # Preview what would be added
bext scaffold add redis --json           # JSON plan output

Fonctionnalités disponibles : auth-jwt, rate-limit, sitemap, analytics, cron, cache, redis, tls, waf, realtime, dev-tools.

Chaque fonctionnalité ajoute : des entrées de configuration à bext.config.toml, des fichiers générés (middleware, gestionnaires, assistants) et des instructions post-ajout.

Drapeau	Défaut	Description
`--dry-run`	FAUX	Afficher le plan sans modifier les fichiers
`--json`	FAUX	Sortie JSON

`bext contribute`#

Échafaudez un nouveau projet de plugin avec le flux de travail de contribution complet.

bash

bext contribute my-auth-plugin                    # Middleware plugin (default)
bext contribute my-transform --kind transform     # Transform plugin
bext contribute my-cache --kind cache-backend     # Cache backend plugin
bext contribute my-hooks --kind lifecycle         # Lifecycle plugin
bext contribute my-plugin --dry-run               # Preview the scaffold

Génère : Cargo.toml (cdylib), src/lib.rs avec trait impl, manifeste plugin.toml, test d'intégration, .gitignore, README.md. Le résultat comprend des instructions étape par étape pour créer, tester et publier.

Drapeau	Défaut	Description
`--kind`	`middleware`	`middleware`, `transform`, `cache-backend`, `lifecycle`
`--author`	`$USER`	Nom de l'auteur
`--description`	auto	Brève description
`--output`	`./<name>`	Répertoire de sortie
`--dry-run`	FAUX	Afficher le plan sans créer de fichiers

`bext format` / `bext lint` / `bext graph`#

Commandes du moteur DX — alimentées par la caisse bext-dx, partagée avec bext-lsp.

bash

bext format                              # Pretty-print bext.config.toml to stdout
bext format --check                      # Exit 1 if not canonical (CI)
bext format --write                      # Overwrite in place
bext lint                                # Lint bext.config.toml
bext lint --json                         # JSON diagnostics
bext lint --strict                       # Warnings → errors
bext graph                               # Plugin/infra/route graph (mermaid)
bext graph --format dot                  # Graphviz output
bext graph --format ascii                # Terminal-friendly
bext graph --format json                 # Machine-readable

Gestion des sites#

`bext sites add`#

Approvisionnement complet du site : une seule commande pour créer un nouveau site avec tout ce qui est câblé.

bash

bext sites add play --domain play.bext.dev              # ISR site (default)
bext sites add api --domain api.bext.dev --rendering ssr # SSR site
bext sites add play --domain play.bext.dev --dry-run    # Preview plan

Automatise le cycle de vie complet :

Échafaudage d'annuaire — bext.config.toml, server/server.ts, package.json, tsconfig.json, layout.tsx, page.tsx
Modules de nœuds — liens symboliques @bext-stack/framework, @bext/ui, react, react -dom
Configuration multi-applications — ajoute l'entrée [[apps]]
Mode mascarade — Blocage du serveur HTTPS nginx, mise à jour HTTP server_name, extension du certificat certbot, rechargement
Non masqué — s'appuie sur [tls] auto_acme pour le provisionnement automatique
Unité Systemd — crée, active et démarre bext-<name>.service

Détection automatique du port : le port proxy et le port du site sont automatiquement dérivés des sites existants.

Drapeau	Défaut	Description
`--domain`	`<name>.bext.dev`	Domaine pleinement qualifié
`--rendering`	`isr`	`isr`, `ssr`, `static`
`--revalidate`	`3600`	Intervalle de revalidation ISR (secondes)
`--port`	auto	Remplacer le port proxy
`--cert-name`	auto	Let's Encrypt nom du certificat à développer
`--no-shared-css`	FAUX	N'utilisez pas de CSS partagé
`--dry-run`	FAUX	Prévisualiser le plan sans l'exécuter
`--json`	FAUX	Sortie du plan JSON
`-y` / `--yes`	FAUX	Passer la confirmation

Autres commandes du site#

bash

bext sites list                          # List all sites
bext sites info <name>                   # Show site details
bext sites deploy <name>                 # Deploy a new version
bext sites rollback <name>              # Rollback to previous version
bext sites versions <name>              # List deployed versions
bext sites remove <name>                 # Remove a site

Utilitaires#

bash

bext version                             # Print version, build, and feature info
bext license                             # Show current license tier, features, and expiry
bext systemd-unit                        # Generate a systemd unit file
bext completions <shell>                 # Generate shell completions (bash, zsh, fish)
bext help                                # Print usage

En rapport#

bext.config.toml — référence de configuration pour chaque indicateur lu par la CLI
Points de terminaison et informations d'identification — Détail des bext config endpoints et bext config credentials
Indicateurs de construction et de fonctionnalités — Fonctionnalités Cargo qui doivent être compilées pour certaines commandes
Guides : Modes de déploiement — bext run contre bext serve contre mascarade
Opérations : codes d'erreur — registre complet pour bext explain

Référence CLI

Commandes principales#

Déploiement#

Gestion des applications#

Gestion du cache#

Gestion des plugins#

Inspection et diagnostic#

Visibilité des points de terminaison#

Gestion des informations d'identification#

Moteur de flux#

Gestion des sauvegardes#

Authentification#

bext login#

bext logout#

bext whoami#

Synchronisation cloud nginx#

Diagnostic#

bext diagnose#

bext logs#

bext llm-hints#

Expérience du développeur#

bext explain#

bext test#

bext scaffold#

bext contribute#

bext format / bext lint / bext graph#

Gestion des sites#

bext sites add#

Autres commandes du site#

Utilitaires#

En rapport#

`bext login`#

`bext logout`#

`bext whoami`#

`bext diagnose`#

`bext logs`#

`bext llm-hints`#

`bext explain`#

`bext test`#

`bext scaffold`#

`bext contribute`#

`bext format` / `bext lint` / `bext graph`#

`bext sites add`#