CLI Reference

Complete reference for the bext command-line interface.

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

Core Commands

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

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

App Management

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

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

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

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

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

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

Create flags:

See Endpoints & Credentials for full details.

Flow Engine

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

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):

--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:

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

Log in to bext cloud via OAuth2. Opens your browser for authentication, then stores credentials locally.

bext login [--cloud-url 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.

bext logout

bext whoami

Show current authentication status and verify token validity.

bext whoami [--cloud-url URL]

nginx Cloud Sync

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.

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

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

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

Output:

  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:

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

bext logs

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

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

Output:

  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:

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

bext llm-hints

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

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.

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

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.

bext scaffold

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

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.

bext contribute

Scaffold a new plugin project with the full contribution workflow.

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.

bext format / bext lint / bext graph

DX engine commands — powered by the bext-dx crate, shared with bext-lsp.

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.

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:

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

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

Other site commands

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

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