CLI Reference

Complete reference for the bext command-line interface.

See docs/platform/02-cli.md in the bext repository for the complete spec.

Tip

Run bext-server check before going to production — it validates your config, confirms ports are reachable, and verifies TLS certificate paths without starting the server.

Core Commands#

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

Deployment#

bash

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

App Management#

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

Cache Management#

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

Plugin Management#

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 & Diagnostics#

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)

Endpoint Visibility#

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

Groups: health, metrics, api, obs, admin. See Endpoints & Credentials for full details.

Credential Management#

bash

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

Create flags:

Flag	Default	Description
`--username`	(required)	Admin username
`--role`	`super_admin`	`super_admin`, `tenant_admin`, or `viewer`
`--password`	(interactive)	Password (hidden prompt when omitted)
`--tenant-id`	(none)	Required for `tenant_admin` role
`--json`	false	Output as JSON instead of TOML

See Endpoints & Credentials for full details.

Flow Engine#

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

Backup Management#

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

Storage flags (apply to all backup subcommands):

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

Create-specific flags:

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)

All flags fall back to the [storage] section in bext.config.toml.

Authentication#

`bext login`#

bash

bext login [--cloud-url URL]

Flag	Default	Description
`--cloud-url`	`https://cloud.bext.dev`	bext cloud URL

Credentials are saved to ~/.bext/credentials.json (mode 0600). After login, all cloud commands (nginx sync-cloud, nginx diff, etc.) automatically use your identity.

`bext logout`#

Remove stored credentials.

bash

bext logout

`bext whoami`#

Show current authentication status and verify token validity.

bash

bext whoami [--cloud-url URL]

nginx Cloud Sync#

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

Each vhost gets a stable 4-character hex ID (derived from its domain list). Use list to see IDs, then sync-cloud --only <id>,<id> to selectively sync.

nginx list shows a framework column with accurate detection (e.g. wordpress, laravel, static). When --json is used, the output includes extended fields: php_fpm_socket, php_version, ssl_cert_path, and ssl_expires_at.

nginx sync-cloud pushes full metadata to the cloud: root paths, PHP-FPM sockets, PHP version, SSL certificate expiry, and action type.

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

Flags:

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)

Diagnostics#

`bext diagnose`#

Connect to a running bext instance and display live diagnostics. Shows health, vhosts, render workers, cache, license, and compiled features.

bash

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

Output:

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)

For LLM/script consumption:

bash

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

Flag	Default	Description
`--pass`	(required)	Admin password for authentication
`--user`	`admin`	Admin username
`--url`	`http://127.0.0.1:80`	Admin API URL
`--format`	`human`	Output format: `human` or `json`

`bext logs`#

Tail recent request logs from a running bext instance with filtering.

bash

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

Output:

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

Filter by status code or path:

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

Flag	Default	Description
`--pass`	(required)	Admin password
`--user`	`admin`	Admin username
`--count`	`50`	Number of entries
`--status`	(all)	Filter: exact code (`500`) or range (`5xx`, `4xx`)
`--path`	(all)	Filter by path prefix
`--format`	`human`	`human` or `json`
`--url`	`http://127.0.0.1:80`	Admin API URL

`bext llm-hints`#

Print structured information about bext for AI/LLM assistants. Includes config schema, available commands, render engines, framework detection, and compiled features.

bash

bext-server llm-hints

This outputs a markdown document that AI assistants can use to understand bext's capabilities and configuration without reading source code.

Developer Experience#

`bext explain`#

Look up any bext error code and get full prose with examples and next steps.

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

Error codes follow the E_<AREA>_<WHAT> pattern. Areas: Config, Plugin, Build, Render, Cache, TLS, WAF, Proxy, Auth, Runtime, Deploy, Upgrade, Secrets, Network. Fuzzy matching suggests the nearest code when no exact match is found.

See Error Codes for the full registry.

`bext test`#

Unified test runner — discovers and runs all test suites across the project.

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

Discovers: cargo test crates, plugin harness binaries, site smoke tests (test.sh), Node/Bun package tests, browser E2E harnesses. The report shows pass/fail per suite with durations.

Flag	Default	Description
`--filter`	(all)	Substring match on suite name
`--kind`	(all)	`cargo`, `node`, `harness`, `browser`, `ecosystem`, `smoke`
`--watch`	false	Re-run affected suites on file change
`--dry-run`	false	List discovered suites without running
`--json`	false	JSON report

`bext scaffold`#

Add common features to an existing site from a curated catalog.

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

Available features: auth-jwt, rate-limit, sitemap, analytics, cron, cache, redis, tls, waf, realtime, dev-tools.

Each feature adds: config entries to bext.config.toml, generated files (middleware, handlers, helpers), and post-add instructions.

Flag	Default	Description
`--dry-run`	false	Show plan without modifying files
`--json`	false	JSON output

`bext contribute`#

Scaffold a new plugin project with the full contribution workflow.

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

Generates: Cargo.toml (cdylib), src/lib.rs with trait impl, plugin.toml manifest, integration test, .gitignore, README.md. The output includes step-by-step instructions to build, test, and publish.

Flag	Default	Description
`--kind`	`middleware`	`middleware`, `transform`, `cache-backend`, `lifecycle`
`--author`	`$USER`	Author name
`--description`	auto	Short description
`--output`	`./<name>`	Output directory
`--dry-run`	false	Show plan without creating files

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

DX engine commands — powered by the bext-dx crate, shared with 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

Site Management#

`bext sites add`#

Full site provisioning — one command to create a new site with everything wired up.

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

Automates the complete lifecycle:

Directory scaffold — bext.config.toml, server/server.ts, package.json, tsconfig.json, layout.tsx, page.tsx
Node modules — symlinks @bext-stack/framework, @bext/ui, react, react-dom
Multi-app config — appends [[apps]] entry
Masquerade mode — nginx HTTPS server block, HTTP server_name update, certbot cert expansion, reload
Non-masquerade — relies on [tls] auto_acme for automatic provisioning
Systemd unit — creates, enables, and starts bext-<name>.service

Port auto-detection: the proxy port and site port are automatically derived from existing sites.

Flag	Default	Description
`--domain`	`<name>.bext.dev`	Fully qualified domain
`--rendering`	`isr`	`isr`, `ssr`, `static`
`--revalidate`	`3600`	ISR revalidation interval (seconds)
`--port`	auto	Override proxy port
`--cert-name`	auto	Let's Encrypt cert name to expand
`--no-shared-css`	false	Don't use shared CSS
`--dry-run`	false	Preview plan without executing
`--json`	false	JSON plan output
`-y` / `--yes`	false	Skip confirmation

Other site commands#

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

Utilities#

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

bext.config.toml — configuration reference for every flag the CLI reads
Endpoints & Credentials — bext config endpoints and bext config credentials detail
Build & Feature Flags — Cargo features that must be compiled in for certain commands
Guides: Deployment Modes — bext run vs bext serve vs masquerade
Operations: Error Codes — full registry for bext explain

CLI Reference

Core Commands#

Deployment#

App Management#

Cache Management#

Plugin Management#

Inspection & Diagnostics#

Endpoint Visibility#

Credential Management#

Flow Engine#

Backup Management#

Authentication#

bext login#

bext logout#

bext whoami#

nginx Cloud Sync#

Diagnostics#

bext diagnose#

bext logs#

bext llm-hints#

Developer Experience#

bext explain#

bext test#

bext scaffold#

bext contribute#

bext format / bext lint / bext graph#

Site Management#

bext sites add#

Other site commands#

Utilities#

Related#

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