CLI Reference
This page is generated by scripts/gen-cli-reference.sh from the--help output of vxl and vxl-admin.
Run vxl help <command> or vxl <command> --help on your installed version for the authoritative output. Connect commands use the server profile selected with vxl server use.
vxl
Deploy and run the software you build on your own server.
Usage: vxl <command> [options]
Get started:
init Create a voxeltron.yaml for this application.
up Build and deploy the application in voxeltron.yaml.
down Remove the application described by voxeltron.yaml.
server Manage SSH and daemon connection profiles.
bootstrap Install Voxeltron on a server over SSH.
Operate:
status Inspect an app's current deployment and deployment history.
logs Read an app's current deployment logs; follow only with -f.
ps List all apps on the server with status and URL.
ls List all apps on the server (alias for ps).
rollback Roll an app's current deployment back to a previous deployment.
restart Restart an app in place with its saved configuration.
deploy Deploy an image, git repository or local source.
db Create, inspect and back up managed databases.
env Set and inspect application environment secrets.
secrets Manage project secrets on the daemon or locally.
doctor Diagnose local setup and remote deployments.
app List applications and inspect their current health.
approvals List, approve and deny self-healing proposals.
audit Export the daemon audit trail.
Advanced:
compose Deploy and manage Docker Compose stacks.
edge Adopt existing containers into managed edge routing.
tunnel Inspect and control the daemon's Cloudflare tunnel.
daemon Upgrade the daemon on a server over SSH.
capabilities Report features implemented by this CLI build.
tui Open the interactive terminal interface.
completion Print a shell completion script.
help Show command usage and examples.
Global flags:
--debug Show diagnostic details (or VXL_DEBUG=1)
--quiet Suppress informational output
--version Show version
--help Show help
Environment:
VXL_SERVER Default server profile for commands with --server
VXL_TOKEN Bearer token fallback for direct and new server connections
Examples:
vxl init
vxl up --yes
vxl daemon upgrade --server prod --release-version v0.1.3
vxl tui
Usage: vxl tui [options]
Flags:
--authorized-keys VALUE Path to authorized_keys file
--connect VALUE gRPC server address
--insecure Allow insecure connections (requires VOXELTRON_ALLOW_INSECURE=1)
--serve Start SSH TUI server
--server VALUE Server profile name
--ssh-port VALUE SSH server port
--theme VALUE Theme: dark, light, synthwave, nord, gruvbox
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl tui --connect localhost:50051
vxl tui --server prod
vxl server
Usage: vxl server <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
add
ls
inspect
use
rm
auth
config
Examples:
sudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400 | vxl server add prod --host 127.0.0.1 --runtime docker --auth-token-stdin
vxl server auth refresh prod
vxl bootstrap
Usage: vxl bootstrap <user@host[:port]> [options]
Flags:
--accept-host-key Explicitly trust and record the presented SSH host key on first use
--domain VALUE Base domain for app routes (e.g. apps.example.com)
--edition VALUE Release edition: community or enterprise
--email VALUE ACME notification email
--host-key-fingerprint VALUE Expected SSH host key fingerprint (SHA256:...)
--json Output JSON
--json-progress Emit NDJSON progress events during bootstrap
--minisign-public-key VALUE Pinned Voxeltron minisign public key
--minisign-public-key-file VALUE File containing the pinned Voxeltron minisign public key
--non-interactive Disable prompts
--port VALUE SSH port
--profile VALUE Profile name to save (defaults to host)
--release-version VALUE exact voxeltrond release version to install (vX.Y.Z)
--runtime VALUE Isolation runtime: firecracker or docker
--ssh-key VALUE SSH private key path
--update-packages Unsupported during bootstrap; use reviewed host maintenance
--yes Auto-approve prompts
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl bootstrap [email protected] --profile prod --runtime docker --accept-host-key --release-version v0.1.3 --minisign-public-key-file ./voxeltron.minisign.pub
vxl daemon
Usage: vxl daemon <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
upgrade
Examples:
vxl daemon upgrade --server prod --release-version v0.1.3
vxl status
Usage: vxl status [app] [options]
Flags:
--app VALUE Application name, defaults to ./voxeltron.yaml
--json Output JSON
--server VALUE Server profile name
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl status shop --server prod
vxl status --json
vxl logs
Usage: vxl logs [app] [options]
Flags:
--app VALUE Application name, defaults to ./voxeltron.yaml
-f Follow logs
--follow Follow logs
--json Output newline-delimited JSON
--server VALUE Server profile name
--since VALUE Duration or RFC3339 timestamp
--tail VALUE Recent line count
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl logs shop --since 10m --tail 50
vxl logs -f
vxl logs shop --json
vxl ps
Usage: vxl ps [app] [options]
Flags:
--json Output JSON
--server VALUE Server profile name
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl ps --server prod
vxl ps --json
vxl ls
Usage: vxl ls [app] [options]
Flags:
--json Output JSON
--server VALUE Server profile name
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl ls --server prod
vxl ls --json
vxl rollback
Usage: vxl rollback [app] [options]
Flags:
--app VALUE Application name, defaults to ./voxeltron.yaml
--server VALUE Server profile name
--to VALUE Previous deployment ID to restore
--yes Confirm rollback without prompting
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl rollback shop
vxl rollback shop --to deployment-id --yes
vxl rollback --app shop --server prod --yes
vxl restart
Usage: vxl restart [app] [options]
Flags:
--app VALUE Application name, defaults to ./voxeltron.yaml
--component VALUE Restart only this component
--server VALUE Server profile name
--yes Confirm restart without prompting
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl restart shop
vxl restart shop --component web --yes
vxl deploy
Usage: vxl deploy <source> [options]
Flags:
--allow-private-domain-fallback Record --domain without verified public routing
--build-arg VALUE Docker build argument KEY=VALUE (repeatable)
--build-engine VALUE Build engine: auto|dockerfile|railpack|nixpacks
--cloudflare-api-base VALUE Cloudflare API base URL
--cloudflare-preflight Run Cloudflare preflight before deployment
--cloudflare-zone VALUE Cloudflare zone for deploy preflight
--dockerfile VALUE Path to Dockerfile (relative to build context, defaults to 'Dockerfile')
--domain VALUE Project domain
--edge VALUE Edge strategy: caddy|cloudflare
--env VALUE Environment variable KEY=VALUE (repeatable)
--env-file VALUE Path to dotenv-style environment file (repeatable)
--follow Stream build and runtime logs in real time (implies --wait)
--git-branch VALUE Git branch to fetch the pinned commit or tag from
--git-commit VALUE Git commit (40-hex sha) to build
--git-tag VALUE Git tag to build, pinned to its commit at fetch time
--handoff Write redacted deployment handoff JSON and Markdown artifacts
--handoff-dir VALUE Directory for deploy --handoff artifacts
--health-grace-period VALUE Grace period before app health checks must pass
--health-interval VALUE App health polling interval
--health-json VALUE JSON health assertion key.path=value (repeatable)
--health-path VALUE App health path to check before marking healthy
--health-status VALUE Expected app health HTTP status
--health-timeout VALUE Per-request app health timeout
--image VALUE Image reference (for image deploys)
--insecure Allow plaintext gRPC (not recommended for remote hosts)
--internal-port VALUE Internal app port for daemon health and origin checks
--json Output JSON
--name VALUE Project name
--preflight Scan local source before deploying
--pull-policy VALUE Pull policy: always|if-not-present|never
--runtime VALUE Runtime selection: auto|firecracker|docker
--runtime-isolation VALUE Runtime isolation, for example docker or firecracker
--runtime-type VALUE Runtime type, for example container or microvm
--server VALUE Server profile
--strategy VALUE Deployment strategy: rolling|blue-green|canary
--timeout VALUE RPC and wait timeout
--type VALUE Source type: auto|image|git|path
--wait Wait for deployment to become healthy
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
status
logs
rollback
Examples:
vxl deploy . --name shop --wait
vxl deploy nginxinc/nginx-unprivileged:1.27-alpine --name web --internal-port 8080
vxl init
Usage: vxl init [options]
Flags:
--domain VALUE Application domain
--file VALUE Manifest file to create
--force Overwrite an existing manifest
--name VALUE Product name
--port VALUE Application port
--with-db VALUE Managed database recipe: postgres or redis (repeatable)
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl init
vxl up
Usage: vxl up [options]
Flags:
--dry-run Print translated DeployProductRequest JSON without RPCs
--file VALUE Manifest file
--insecure Allow plaintext gRPC
--json Output JSON
--max-source-bytes VALUE Maximum source archive and expanded size in bytes
--server VALUE Server profile
--timeout VALUE RPC timeout
--yes Confirm mutation
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl up --dry-run
vxl up --yes --server prod --json
vxl down
Usage: vxl down [options]
Flags:
--file VALUE Manifest file
--insecure Allow plaintext gRPC
--json Output JSON
--purge-data Permanently delete retained service data after confirmation
--server VALUE Server profile
--timeout VALUE RPC timeout
--yes Confirm mutation
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl down --yes --server prod --json
vxl deploy-product
Usage: vxl deploy-product <manifest.toml> [options]
Flags:
--cloudflare-provider VALUE Cloudflare executor: direct, fallback, or auto
--dry-run Print the plan without changing infrastructure
--env VALUE Manifest environment to deploy
--insecure Allow plaintext daemon gRPC
--json Output machine-readable JSON
--leave-infrastructure Rollback guidance leaves Cloudflare tunnel/DNS infrastructure in place
--pack VALUE App pack to deploy instead of a manifest
--require-persisted-secrets Require secret:// values to resolve from a persisted local secret lane
--secret-source VALUE Secret source for secret:// values, for example sops://private/deploy/staging.sops.env
--source-sync VALUE Engine source sync mode: daemon or ssh-rsync
--timeout VALUE Overall deploy timeout
--wait Wait for engine deployment and run smoke tests
--yes Apply without interactive prompts
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
rollback
repair-cloudflared
Examples:
vxl deploy-product manifest.toml --env staging --dry-run
vxl app
Usage: vxl app <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
list
status
fix
Examples:
vxl app list --server prod
vxl app status --name shop
vxl app fix --apply
vxl secrets
Usage: vxl secrets <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
list
get
set
delete
copy
local
Examples:
vxl secrets list --project shop
vxl secrets list --server prod --json
vxl db
Usage: vxl db <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
create
list
conn
psql
backup
backups
restore
delete
Examples:
vxl db create appdb --engine postgres --project shop
vxl db list --server prod --json
vxl approvals
Usage: vxl approvals <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
list
approve
deny
Examples:
vxl approvals list
vxl approvals approve <id>
vxl approvals deny <id>
vxl audit
Usage: vxl audit <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
export
Examples:
vxl audit export --format json
vxl doctor
Usage: vxl doctor <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
install
route
container
edge-proxy
microvm
app
local
remote
Examples:
vxl doctor local
vxl doctor remote --server prod
vxl tunnel
Usage: vxl tunnel <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
status
enable
disable
Examples:
vxl tunnel status --address localhost:50051
vxl compose
Usage: vxl compose <subcommand> [options]
Flags:
--insecure Allow plaintext gRPC (not recommended for remote hosts)
--server VALUE Server profile name
--timeout VALUE RPC timeout (0 disables timeout)
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
delete
deploy
down
list
logs
up
update
validate
Examples:
vxl compose list --server prod
vxl compose validate --file compose.yaml --project shop --name web
vxl capabilities
Usage: vxl capabilities [options]
Flags:
--json print the capability list as a JSON object
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl capabilities --json
vxl edge
Usage: vxl edge <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
adopt
Examples:
vxl edge adopt --server prod
vxl edge adopt --address localhost:50051
vxl cloudflare
Usage: vxl cloudflare <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
doctor
Examples:
vxl cloudflare doctor --zone example.com
vxl app-pack
Usage: vxl app-pack <subcommand> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Subcommands:
inspect
install
Examples:
vxl app-pack inspect ./pack --json
vxl server add
Usage: vxl server add <name> [options]
Flags:
--accept-host-key Explicitly trust and record the presented SSH host key on first use
--auth-token VALUE Bearer token for API authentication
--auth-token-stdin Read the bearer token from stdin
--ca-cert VALUE Path to CA certificate for TLS server-auth
--client-cert VALUE Path to client certificate for mTLS
--client-key VALUE Path to client private key for mTLS
--grpc-addr VALUE gRPC address (default: <host>:50051)
--host VALUE Server host or IP
--host-key-fingerprint VALUE Expected SSH host key fingerprint (SHA256:...)
--key VALUE SSH private key path
--port VALUE SSH port
--proof-expires VALUE Lifetime for temporary proof profiles (for example 30m)
--proof-purpose VALUE Purpose label for temporary proof profiles
--runtime VALUE Isolation runtime: firecracker or docker
--skip-verify Skip TLS certificate verification (requires VOXELTRON_ALLOW_INSECURE=1)
--ssh-tunnel Use authenticated SSH stdio transport for gRPC
--user VALUE SSH user
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
sudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400 | vxl server add prod --host 127.0.0.1 --runtime docker --auth-token-stdin
ssh [email protected] sudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400 | vxl server add prod --host 203.0.113.10 --user admin --runtime docker --ssh-tunnel --accept-host-key --auth-token-stdin
vxl server ls
Usage: vxl server ls [options]
Flags:
--json Output JSON
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl server ls
vxl server use
Usage: vxl server use <name> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl server use prod
vxl server rm
Usage: vxl server rm <name> [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl server rm staging
vxl server inspect
Usage: vxl server inspect <name> [options]
Flags:
--json Output JSON
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl server inspect prod
vxl server auth status
Usage: vxl server auth status <name> [options]
Flags:
--json Output JSON
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl server auth status prod
vxl server auth refresh
Usage: vxl server auth refresh <name> [options]
Flags:
--json Output JSON
--ttl-seconds VALUE Lifetime of the replacement token
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl server auth refresh prod
vxl server config validate
Usage: vxl server config validate <name> [options]
Flags:
--candidate VALUE Local candidate configuration to validate remotely
--json Output JSON
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl server config validate prod
vxl daemon upgrade
Usage: vxl daemon upgrade [options]
Flags:
--edition VALUE Release edition: community or enterprise
--host VALUE Direct SSH target user@host[:port]
--json Output JSON
--minisign-public-key VALUE Pinned Voxeltron minisign public key
--minisign-public-key-file VALUE File containing the pinned Voxeltron minisign public key
--port VALUE SSH port for --host
--release-version VALUE exact voxeltrond release version to install (vX.Y.Z)
--runtime VALUE Isolation runtime: firecracker or docker
--server VALUE Server profile name
--ssh-key VALUE SSH private key path
--verify-config Validate /etc/voxeltron/voxeltron.toml with the replacement daemon before restart
--verify-runtime-compat Verify installed guest runtime helpers are compatible before restart
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl daemon upgrade --server prod --release-version v0.1.3
vxl deploy status
Usage: vxl deploy status [options]
Flags:
--deployment-id VALUE Deployment ID
--json Output JSON
--name VALUE Project name
--server VALUE Server profile name
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl deploy status --name shop --server prod
vxl deploy logs
Usage: vxl deploy logs [options]
Flags:
--deployment-id VALUE Deployment ID (required)
--follow Follow log stream
--json Output JSON lines
--server VALUE Server profile name
--since VALUE Only logs since RFC3339 timestamp
--tail VALUE Tail line count
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl deploy logs --deployment-id deployment-id --server prod
vxl deploy rollback
Usage: vxl deploy rollback <deployment-id> [options]
Flags:
--json json
--server VALUE server
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl deploy rollback deployment-id --server prod
vxl app list
Usage: vxl app list [options]
Flags:
--json Output JSON
--server VALUE Server profile name
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl app list --server prod
vxl app status
Usage: vxl app status [options]
Flags:
--json Output JSON
--name VALUE App/project name
--port VALUE Preferred container port, for example 8080/tcp
--server VALUE Server profile name
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl app status --name shop --server prod
vxl db create
Usage: vxl db create <name> [options]
Flags:
--engine VALUE Database engine: postgres, mysql, redis, mongodb
--insecure Allow plaintext gRPC
--json Output JSON
--project VALUE Project name
--server VALUE Server profile
--timeout VALUE RPC timeout
--version VALUE Engine version (defaults: postgres 16, mysql 8.4, redis 7.4, mongodb 7.0)
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl db create appdb --engine postgres --project shop
vxl db list
Usage: vxl db list [options]
Flags:
--insecure Allow plaintext gRPC
--json Output JSON
--project VALUE Project name
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl db list --server prod
vxl db conn
Usage: vxl db conn <name> [options]
Flags:
--as-secret Store the URL as a project secret and print its reference
--insecure Allow plaintext gRPC
--project VALUE Project name
--server VALUE Server profile
--show-password Print the password even on a terminal
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl db conn appdb --server prod
vxl db psql
Usage: vxl db psql <name> [options]
Flags:
--insecure Allow plaintext gRPC
--project VALUE Project name
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Open psql inside the managed database container over SSH. Only PostgreSQL is supported.
Configure SSH access with vxl server add <name> --ssh-tunnel.
The database password never leaves the server.
Examples:
vxl db psql appdb --server prod
vxl db backup
Usage: vxl db backup <name> [options]
Flags:
--insecure Allow plaintext gRPC
--project VALUE Project name
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl db backup appdb --server prod
vxl db backups
Usage: vxl db backups <name> [options]
Flags:
--insecure Allow plaintext gRPC
--json Output JSON
--project VALUE Project name
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl db backups appdb --server prod
vxl db restore
Usage: vxl db restore <name> --backup <id> [options]
Flags:
--backup VALUE Backup ID
--insecure Allow plaintext gRPC
--json Output JSON
--project VALUE Project name
--server VALUE Server profile
--timeout VALUE RPC timeout
--yes Confirm the restore
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl db restore appdb --backup backup-id --server prod
vxl db delete
Usage: vxl db delete <name> [options]
Flags:
--insecure Allow plaintext gRPC
--project VALUE Project name
--server VALUE Server profile
--timeout VALUE RPC timeout
--yes Confirm the deletion
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl db delete appdb --server prod
vxl secrets list
Usage: vxl secrets list [options]
Flags:
--address VALUE address
--all all
--insecure insecure
--json json
--project VALUE project
--server VALUE server
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl secrets list --project shop --server prod
vxl secrets get
Usage: vxl secrets get <key> [options]
Flags:
--address VALUE address
--all all
--insecure insecure
--json json
--project VALUE project
--server VALUE server
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl secrets get API_TOKEN --project shop --server prod
vxl secrets set
Usage: vxl secrets set <key> <value|-> [options]
Flags:
--address VALUE address
--all all
--insecure insecure
--json json
--project VALUE project
--server VALUE server
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl secrets set API_TOKEN - --project shop --server prod
vxl secrets delete
Usage: vxl secrets delete <key> [options]
Flags:
--address VALUE address
--all all
--insecure insecure
--json json
--project VALUE project
--server VALUE server
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl secrets delete API_TOKEN --project shop --server prod
vxl secrets copy
Usage: vxl secrets copy <key> <target-project> [options]
Flags:
--address VALUE address
--all all
--insecure insecure
--json json
--project VALUE project
--server VALUE server
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl secrets copy API_TOKEN staging --project shop --server prod
vxl env set
Usage: vxl env set [KEY=VALUE...] [options]
Flags:
--app VALUE app
--file VALUE file
--insecure insecure
--redeploy redeploy
--reveal reveal
--server VALUE server
--timeout VALUE timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl env shop set API_TOKEN -
vxl env ls
Usage: vxl env ls [KEY=VALUE...] [options]
Flags:
--app VALUE app
--file VALUE file
--insecure insecure
--redeploy redeploy
--reveal reveal
--server VALUE server
--timeout VALUE timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl env shop ls
vxl env unset
Usage: vxl env unset [KEY=VALUE...] [options]
Flags:
--app VALUE app
--file VALUE file
--insecure insecure
--redeploy redeploy
--reveal reveal
--server VALUE server
--timeout VALUE timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl env shop unset API_TOKEN
vxl doctor local
Usage: vxl doctor local [options]
Flags:
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl doctor local
vxl doctor remote
Usage: vxl doctor remote [options]
Flags:
--accept-buildkit-cache-loss Acknowledge BuildKit cache loss before retiring an unmanaged BuildKit helper
--accept-retained-artifact-cleanup Acknowledge guarded cleanup of an archived retained Docker artifact
--accept-stateful-data-retirement Acknowledge guarded retirement of an idle stateful service while preserving backup and data volumes
--archive-stale-compose-reference Archive a stale compose/env file to /var/lib/voxeltron/stale-config/
--artifact-kind VALUE Retained Docker artifact kind for guarded cleanup: volume or network
--artifact-name VALUE Exact retained Docker volume or network name for guarded cleanup
--backup-dir VALUE Remote directory for guarded stateful service backups
--backup-path VALUE Remote backup artifact path for guarded stateful service restore rehearsal
--backup-stateful-service Create a guarded backup proof for an unmanaged stateful service
--container-name VALUE Exact BuildKit helper container name for guarded retirement
--domain VALUE Domain to validate for DNS/ACME checks
--inspect-stateful-service Read-only inspect of an unmanaged stateful service for migration planning
--json Output structured JSON
--path VALUE Path to the stale compose/env file to archive
--prepare-stateful-replacement Prepare an isolated candidate stateful replacement from a verified backup
--profile VALUE Doctor profile: staging-acceptance summarizes host-isolation blockers and returns non-zero when staging is not clean
--rehearse-stateful-restore Rehearse restoring a guarded stateful service backup in a disposable isolated runtime
--replacement-name VALUE Exact replacement container name for guarded stateful migration preparation
--replacement-network VALUE Exact isolated Docker network name for guarded stateful migration preparation
--retire-idle-buildkit-helper Retire an unmanaged BuildKit helper after confirming no active builds and accepting cache loss
--retire-idle-stateful-service Retire an idle unmanaged stateful service after backup, no-client, and no-exposure proof while preserving data volumes
--retire-retained-artifact Archive and remove an exact retained Docker volume or empty network after approval
--retire-stateful-replacement Retire an isolated Voxeltron-managed stateful replacement candidate and its managed proof resources
--server VALUE Server profile name
--skip-ssh Skip SSH command checks and only run network/gRPC checks
--trace-stateful-app-references Read-only trace of daemon and MicroVM app references to an unmanaged stateful service
--trace-stateful-clients Read-only trace of containers sharing networks with an unmanaged stateful service
--trace-stateful-external-exposure Read-only trace of externally published ports for an unmanaged stateful service
--trace-stateful-host-references Read-only trace of host-level references to an unmanaged stateful service
--verify-stateful-replacement-isolation Verify a candidate stateful replacement container has bounded isolation
--verify-stateful-replacement-readiness Verify a candidate stateful replacement accepts same-network client connections
--yes Confirm guarded remote repair execution
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl doctor remote --server prod
vxl doctor app
Usage: vxl doctor app [options]
Flags:
--health-json VALUE JSON health assertion key.path=value (repeatable)
--health-path VALUE Health path to probe
--json Output JSON
--name VALUE App/project name
--server VALUE Server profile name
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl doctor app --name shop --server prod
vxl doctor route
Usage: vxl doctor route [options]
Flags:
--artifact-out VALUE Write route proof JSON artifact to this path
--cloudflare-account-id VALUE Cloudflare account ID for tunnel readback
--cloudflare-api-base VALUE Cloudflare API base URL
--cloudflare-tunnel-id VALUE Cloudflare tunnel ID for tunnel readback
--deployment-id VALUE Current deployment ID
--hostname VALUE Tunnel ingress hostname to read from Cloudflare
--include-host-listeners Include host TCP listeners and Docker route candidates
--include-host-runtime Include Firecracker VM systemd units found on the host
--json Output structured JSON
--marker-header VALUE Header containing the public deployment marker
--origin-url VALUE Daemon-reported verified origin URL
--origin-verified Whether the daemon verified the origin
--proxy-name VALUE Exact edge proxy container name for guarded route repair
--public-healthy Whether public route health passed
--public-marker VALUE Deployment marker observed from public route
--public-url VALUE Public route URL to probe for health and deployment marker
--retire-stale-edge-proxy Retire an unmanaged host-network edge proxy proven stale by route proof
--route-proof VALUE Path to doctor route JSON proof for guarded route repairs
--route-proof-dir VALUE Directory to use when --artifact-out=auto
--route-proof-max-age VALUE Maximum age for guarded route proof artifacts
--server VALUE Server profile name for daemon deployment lookup
--tunnel-service VALUE Provider tunnel service readback
--yes Confirm guarded route repair execution
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl doctor route --deployment-id deployment-id --server prod
vxl doctor container
Usage: vxl doctor container [options]
Flags:
--cloudflare-account-id VALUE Cloudflare account ID for generated repair-plan route proof
--cloudflare-api-base VALUE Cloudflare API base URL for generated repair-plan route proof
--cloudflare-tunnel-id VALUE Cloudflare tunnel ID for generated repair-plan route proof
--deployment-id VALUE Deployment ID to inspect
--execute-repair Execute the guarded container replacement, route proof, and quarantine repair flow
--hostname VALUE Tunnel ingress hostname for generated repair-plan route proof
--include-host-listeners Include host listener inventory in generated repair-plan route proof
--include-host-runtime Include host runtime inventory in generated repair-plan route proof
--json Output structured JSON
--marker-header VALUE Header containing the public deployment marker in generated repair-plan route proof
--public-url VALUE Public route URL to probe in generated repair-plan route proof
--quarantine Quarantine a superseded container deployment after replacement route proof
--repair-plan Output a non-mutating repair plan for container hardening drift
--route-proof VALUE Path to doctor route JSON proof before quarantining a live container runtime
--route-proof-dir VALUE Directory to search when --route-proof=auto
--route-proof-max-age VALUE Maximum age for route proof artifacts
--server VALUE Server profile name
--yes Confirm repair execution
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl doctor container --deployment-id deployment-id --server prod
vxl edge adopt
Usage: vxl edge adopt [domain...] [options]
Flags:
--address VALUE address
--all all
--insecure insecure
--json json
--server VALUE server
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl edge adopt --server prod
vxl cloudflare doctor
Usage: vxl cloudflare doctor [options]
Flags:
--api-base VALUE Cloudflare API base URL
--json Output structured JSON
--zone VALUE Cloudflare zone name or routed domain
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl cloudflare doctor --zone example.com
vxl approvals list
Usage: vxl approvals list [options]
Flags:
--insecure Allow plaintext gRPC
--json Output JSON
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl approvals list --server prod
vxl approvals approve
Usage: vxl approvals approve <id> [options]
Flags:
--insecure Allow plaintext gRPC
--json Output JSON
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl approvals approve 4f0c9a5e-6c1b-4f7e-9d0a-2b8f1e3c7d21 --server prod
vxl approvals deny
Usage: vxl approvals deny <id> [options]
Flags:
--insecure Allow plaintext gRPC
--json Output JSON
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl approvals deny 4f0c9a5e-6c1b-4f7e-9d0a-2b8f1e3c7d21 --server prod
vxl audit export
Usage: vxl audit export [options]
Flags:
--format VALUE Output format: json (one object per line) or csv
--insecure Allow plaintext gRPC
--server VALUE Server profile
--timeout VALUE RPC timeout
--help, -h Show help
Global flags:
--debug Show diagnostic details
--quiet Suppress informational output
Examples:
vxl audit export --format csv --server prod
vxl-admin
Usage: vxl-admin [OPTIONS] [COMMAND]
Commands:
backup Backup and restore persistent data (compress + encrypt + upload)
platform Validate and resolve declarative platform manifests
doctor Diagnose and reconcile lifecycle reaper state
node Bring a host to a Host Baseline (firewall/sysctl/systemd), idempotent + fail-safe
cell Operate on running cells (e.g. operator exec inside a guest)
deploy Deploy a product through voxeltrond's authenticated gRPC API
create-deployment Build-from-source (git/local-path/Dockerfile) or deploy a pre-built image for a single component via voxeltrond's CreateDeployment API
delete-deployment Delete a deployment by product id, component deployment id, or runtime id
serve Launch a GPU/LLM OpenAI-compatible serving container
update Replace voxeltrond locally, restart systemd, health-check, and roll back on failure
help Print this message or the help of the given subcommand(s)
Options:
--config <CONFIG> [default: /etc/voxeltron/voxeltron.toml]
--log-level <LOG_LEVEL> [default: info]
--dev
--no-daemon
--validate-config
-h, --help Print help
-V, --version Print version
vxl-admin backup
Backup and restore persistent data (compress + encrypt + upload)
Usage: vxl-admin backup <COMMAND>
Commands:
create Compress, encrypt, and upload a file or directory to a backup target
restore Download, decrypt, and decompress a backup to a local file
list List backups under a target, optionally scoped to a subdirectory prefix
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
vxl-admin platform
Validate and resolve declarative platform manifests
Usage: vxl-admin platform <COMMAND>
Commands:
preflight Validate a platform manifest (fail closed)
resolve Resolve a manifest into a structural lock (prints JSON)
inject Render a component /etc/env injection plan
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
vxl-admin doctor
Diagnose and reconcile lifecycle reaper state
Usage: vxl-admin doctor <COMMAND>
Commands:
reap Plan or execute lifecycle orphan reaping
status Print lifecycle health and orphan summary
audit Read-only host posture audit (no mutation)
reboot-readiness Audit whether this host would recover Firecracker products across a cold boot (read-only)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
vxl-admin node
Bring a host to a Host Baseline (firewall/sysctl/systemd), idempotent + fail-safe
Usage: vxl-admin node <COMMAND>
Commands:
harden Bring this host to a Host Baseline (idempotent). MUTATES the host unless --dry-run. HFW-001 blocks configured TCP ports on host INPUT and persists via a boot unit. FW-001 fences new forwarded ingress to Docker bridges, including published 80/443, when default_ingress is deny and bridges exist (runtime-only). host INPUT default-deny and allow_ingress are not enforced. There is NO remote-lockout guard yet (VX-HF-C)
control-tls Activate or rotate the fixed production control-plane TLS identity
operator-admin Converge one operator principal into security.operator_admins (atomic, idempotent single-file convergence)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
vxl-admin cell
Operate on running cells (e.g. operator exec inside a guest)
Usage: vxl-admin cell <COMMAND>
Commands:
exec Run a command inside a running cell's guest over the operator path
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
vxl-admin deploy
Deploy a product through voxeltrond's authenticated gRPC API
Usage: vxl-admin deploy [OPTIONS] --request <REQUEST>
Options:
--request <REQUEST> Path to a DeployProductRequest JSON file
--endpoint <ENDPOINT> gRPC endpoint of voxeltrond [default: https://127.0.0.1:50051]
--insecure Skip TLS certificate verification, matching grpcurl -insecure
--ca-cert <CA_CERT> PEM CA/server certificate used to verify the TLS endpoint
--tls-domain <TLS_DOMAIN> Override the TLS certificate domain/SAN used for verification
--token <TOKEN> Bearer token for the authed gRPC plane. If omitted, mint one from --config
--config <CONFIG> Config path to mint a token from (used when --token is not given) [default: /etc/voxeltron/voxeltron.toml]
-h, --help Print help
vxl-admin create-deployment
Build-from-source (git/local-path/Dockerfile) or deploy a pre-built image for a single component via voxeltrond's CreateDeployment API
Usage: vxl-admin create-deployment [OPTIONS] --project-id <PROJECT_ID>
Options:
--project-id <PROJECT_ID> Project/component id for the deployment
--git <GIT> Build from a git repository URL
--git-ref <GIT_REF> Git ref (branch, tag, or commit) used with --git
--source-path <SOURCE_PATH> Build from a local source path
--image <IMAGE> Deploy a pre-built image without building
--dockerfile <DOCKERFILE> Dockerfile path (relative to the build context)
--context <CONTEXT> Build context path (relative to the source root)
--engine <ENGINE> Build engine [default: auto] [possible values: auto, railpack, nixpacks, dockerfile]
--env <KEY=VALUE> Environment variable as KEY=VALUE (repeatable)
--strategy <STRATEGY> Deployment strategy [default: recreate] [possible values: rolling, blue-green, canary, recreate]
--pull-policy <PULL_POLICY> Image pull policy [default: if-not-present] [possible values: always, if-not-present, never]
--detach Return immediately; build+deploy run in the background (stream via logs)
--endpoint <ENDPOINT> gRPC endpoint of voxeltrond [default: https://127.0.0.1:50051]
--insecure Skip TLS certificate verification
--ca-cert <CA_CERT> PEM CA/server certificate used to verify the TLS endpoint
--tls-domain <TLS_DOMAIN> Override the TLS certificate domain/SAN used for verification
--token <TOKEN> Bearer token for the authed gRPC plane. If omitted, mint one from --config
--config <CONFIG> Config path to mint a token from (used when --token is not given) [default: /etc/voxeltron/voxeltron.toml]
-h, --help Print help
vxl-admin delete-deployment
Delete a deployment by product id, component deployment id, or runtime id
Usage: vxl-admin delete-deployment [OPTIONS] <ID>
Arguments:
<ID> Product id, component deployment id, or runtime id to delete
Options:
--endpoint <ENDPOINT> gRPC endpoint of voxeltrond [default: https://127.0.0.1:50051]
--insecure Skip TLS certificate verification, matching grpcurl -insecure
--ca-cert <CA_CERT> PEM CA/server certificate used to verify the TLS endpoint
--tls-domain <TLS_DOMAIN> Override the TLS certificate domain/SAN used for verification
--token <TOKEN> Bearer token for the authed gRPC plane. WARNING: passing a token here exposes the credential in process arguments (visible to other users via `ps`). Prefer --subject, which mints a short-lived token in-process from --config. If neither is given, a token is minted from --config
--subject <SUBJECT> Principal the internally minted token is issued for. System-owned product records (empty secrets_project_id) require a principal listed in [security].operator_admins, e.g. voxeltron-update. Conflicts with --token [default: voxeltron-delete]
--config <CONFIG> Config path to mint a token from (used when --token is not given) [default: /etc/voxeltron/voxeltron.toml]
-h, --help Print help
vxl-admin serve
Launch a GPU/LLM OpenAI-compatible serving container
Usage: vxl-admin serve [OPTIONS] <ENGINE> <PORT>
Arguments:
<ENGINE> Serving engine to launch: vllm, sglang, or lucebox
<PORT> OpenAI-compatible API port exposed to cells
Options:
--image <IMAGE> Override the engine's default image
--vxbr0-gw <VXBR0_GW> vxbr0 gateway address cells use to reach host-bound services [default: 172.31.0.1]
--registry <REGISTRY> Component registry path updated after the health gate passes [default: /var/lib/voxeltron/firecracker/deployed_components.json]
--product-id <PRODUCT_ID> Product id recorded in the component registry [default: gpu-llm]
--max-attempts <MAX_ATTEMPTS> Maximum OpenAI `/v1/models` health probe attempts [default: 30]
--env <KEY=VALUE> Environment variable (`KEY=VALUE`), repeatable. Used by engines that configure models via env (e.g. lucebox `DFLASH_TARGET`/`DFLASH_DRAFT`)
--volume <HOST:CONTAINER> Bind mount (`HOST:CONTAINER`), repeatable. Mounts model weights / caches
--memory-gb <GB> Host RAM cap in GiB; default unlimited (GPU serving needs the whole box's RAM for the model)
--arg <ARG> Engine command argument, repeatable. Used by engines configured via the command line (e.g. vllm/sglang `--model <id>`)
--user <USER> Container user (`uid[:gid]` or name). Defaults to the image's own user; GPU serving images typically need root to reach the GPU + model weights
-h, --help Print help
vxl-admin update
Replace voxeltrond locally, restart systemd, health-check, and roll back on failure
Usage: vxl-admin update [OPTIONS] --binary <BINARY>
Options:
--binary <BINARY>
Path to the new voxeltrond binary to install
--release-signature <RELEASE_SIGNATURE>
Raw Ed25519 release signature for --binary (required with --remote-grpc)
--allow-same-version-rebuild
Permit a same-SemVer rebuild: the candidate may equal the installed version only when its content digest differs from the installed daemon. Local updates only; rejected with --remote-grpc
--dest <DEST>
Destination path of the running daemon binary to replace [default: /usr/local/bin/voxeltrond]
--service <SERVICE>
systemd unit to restart [default: voxeltrond.service]
--health-url <HEALTH_URL>
Health URL polled after restart (must return the Voxeltron ready contract) [default: http://127.0.0.1:7103/health]
--remote <REMOTE>
Retired SSH transport. Remote updates must use --remote-grpc
--remote-grpc <REMOTE_GRPC>
gRPC endpoint of the remote voxeltrond for an mTLS self-upgrade
--mtls-ca <MTLS_CA>
PEM CA/server certificate used to verify the remote voxeltrond TLS endpoint
--mtls-cert <MTLS_CERT>
PEM client certificate presented for mutual TLS
--mtls-key <MTLS_KEY>
PEM client private key presented for mutual TLS
--tls-domain <TLS_DOMAIN>
Override the TLS certificate domain/SAN used for verification
--token <TOKEN>
Bearer token for the authed gRPC plane. If omitted, mint one from --config
--config <CONFIG>
Config path to mint a token from (used when --token is not given) [default: /etc/voxeltron/voxeltron.toml]
--timeout-secs <TIMEOUT_SECS>
Seconds to wait for health before rolling back (brownfield updates require at least 180; the operator default is 180) [default: 180]
--plan
Plan only: print what would happen, mutate nothing
--recover-restart-loop
Explicit escape hatch for a fixed brownfield daemon stuck in a restart loop: stop the unit, reinstall the staged candidate, and re-prove strict health across repeated polls before commit. Local only, fixed-brownfield-only, never with --plan. A healthy unit is refused (this is not an alternate normal update path). Same-version reinstalls require --allow-same-version-rebuild; downgrades and byte-identical rebuilds stay forbidden
-h, --help
Print help