CLI reference

z4j ships a CLI named z4j. Runs inside the container or from a local pip install.

z4j --help

Serving

serve

z4j serve [--host 0.0.0.0] [--port 7700] [--workers 1]

Starts the FastAPI application via Uvicorn. This is the container entrypoint.

Health and diagnostics

check

z4j check

Validates config and DB connectivity and confirms Alembic is at head. Non-destructive. Exit 0 = healthy.

doctor

z4j doctor

Runs a full health and configuration audit: env-var coverage, DB reachability, Alembic head, registry backend probe, metrics-token resolution, scheduler trigger reachability if configured, mTLS cert validity. Verbose by design; pair with --json for machine output.

status

z4j status

Prints a summary of current brain state: version, Alembic head, environment, database URL, and row counts (users, projects, agents, tasks, active sessions, audit rows).

version

z4j version

Prints the installed z4j version.

First-boot setup

init

z4j init

Scaffolds ~/.z4j/config.env with the required Z4J_* variables for a local install (database URL, secrets, public URL). Idempotent; refuses to overwrite an existing file unless --force is supplied.

bootstrap-admin

z4j bootstrap-admin --email you@example.com --display-name "You"

Creates the initial admin user and the default project. First-boot only.

createsuperuser

z4j createsuperuser --email you@example.com --display-name "You" --password-stdin

Django-friendly alias for bootstrap-admin. Use --password-stdin to pipe the password in from a secret manager.

changepassword

z4j changepassword you@example.com --password-stdin

Changes a user’s password. Intended for admin recovery / CLI-only ops when the user cannot reach the dashboard reset flow.

reset-mfa

z4j reset-mfa user@example.com
z4j reset-mfa user@example.com --confirm     # skip the interactive prompt

Operator escape hatch for the lost-phone-AND-lost-recovery-codes case. Clears the user’s MFA secret, recovery codes, and trusted devices in one transaction; writes a user.mfa_reset_by_admin audit row attributed to the OS user running the CLI. Shell-only by design — there is no REST surface so an attacker who has only the dashboard cannot trigger it. See Multi-factor authentication for context.

Configuration

config show

z4j config show

Prints the resolved effective settings (post-env-var, post-defaults, post-~/.z4j/config.env). Secrets are masked. Mirrors the GET /api/v1/admin/settings endpoint.

config validate

z4j config validate

Loads the settings and reports any validation failure (missing required field, out-of-range value, malformed URL) without booting the rest of the app. Exit 0 = valid.

Backups

backup

z4j backup --output /var/backups/z4j-$(date +%Y-%m-%d).db

Snapshots the brain database to a single file. On SQLite, a VACUUM INTO clone; on Postgres, a pg_dump --format=custom plus a manifest. The destination is overwritten if it exists; pass --no-clobber to refuse.

restore

z4j restore /var/backups/z4j-pre-upgrade.db --force

Restores from a backup file produced by z4j backup. Refuses to run while another brain has the DB open unless --force is given.

Maintenance and upgrades

migrate

z4j migrate upgrade head
z4j migrate current
z4j migrate history
z4j migrate downgrade <revision>

Runs an Alembic command against the brain database.

upgrade

z4j upgrade
z4j upgrade --check

Checks PyPI for newer releases of z4j and any installed z4j-* adapters; --check prints what would change without installing. Mirrors POST /api/v1/admin/system/versions/check on the API side. The actual install path defers to the operator (running pip / Helm / Docker pull); the command surfaces the manifest so the operator can plan the upgrade.

Allowed hosts

allowed-hosts list / add / remove / path

z4j allowed-hosts list
z4j allowed-hosts add z4j.example.com
z4j allowed-hosts remove old-host.example.com
z4j allowed-hosts path

Manages the persistent Host header allow-list (Z4J_ALLOWED_HOSTS). path prints the file the brain reads from so operators can edit it directly. See allowed hosts.

Audit log

audit verify

z4j audit verify

Walks the full HMAC-chained audit log. Exit 0 on success, 1 on broken chain.

Tokens and certs

metrics-token

z4j metrics-token              # print the active token
z4j metrics-token rotate       # mint a new token; old one stops working

Manages the bearer that gates /metrics. Resolution order: Z4J_METRICS_AUTH_TOKEN, ~/.z4j/secret.env, auto-minted on first boot.

mint-scheduler-cert

z4j mint-scheduler-cert --cn scheduler-prod-1 --out /etc/z4j/pki/

Mints a fresh mTLS client certificate for a z4j-scheduler instance to authenticate to the brain. Adds the CN to the Z4J_SCHEDULER_GRPC_ALLOWED_CNS allow-list if requested with --allow-list. See production hardening.

Destructive

reset-setup

z4j reset-setup

Wipes pending first-boot tokens and recent setup audit rows. Refuses if an admin user already exists; use reset for a full wipe.

reset

z4j reset            # refuses without --force
z4j reset --force

Wipes every runtime table (users, sessions, projects, agents, tasks, events, schedules, audit, …). Schema stays; Alembic does not re-run. Leaves z4j in a pre-first-boot state.

Global flags

Flag	Description
-h, --help	Show help for the command

Per-command flags surface with z4j <command> --help.

z4j-scheduler CLI

When you run the standalone scheduler service, the z4j-scheduler CLI ships these commands. See z4j-scheduler for deployment context.

z4j-scheduler serve                        # run the scheduler process
z4j-scheduler version                      # print installed version
z4j-scheduler check --brain-grpc-url ...   # one-line pass/fail health
z4j-scheduler status                       # introspection (not yet implemented; stub)
z4j-scheduler info                         # resolved settings (not yet implemented; stub)
z4j-scheduler doctor                       # comprehensive diagnostics
z4j-scheduler restart                      # informational stub (delegates to systemd / k8s)
z4j-scheduler import --from <tool> ...     # migrate from celery-beat / rq / apscheduler / cron
z4j-scheduler export --to <tool> ...       # reverse-export
z4j-scheduler schedules add / list / trigger / disable / enable / edit / history ...

All commands accept --help. Most read configuration from Z4J_SCHEDULER_* env vars; explicit flags win where provided.

Framework adapter CLIs

Each framework adapter ships its own doctor plus a few helpers under python -m z4j_<framework>:

python -m z4j_bare doctor              # canonical implementation
python -m z4j_flask doctor             # same checks; reads Flask app.config or env
python -m z4j_fastapi doctor           # same checks; reads env
python -m z4j_django doctor            # equivalent Django management command: ./manage.py z4j_doctor

All four implement doctor with the same probes (buffer dir writable, brain DNS / TCP / TLS, WebSocket upgrade) and accept the same flags (--no-websocket, --json). See frameworks/bare for the canonical reference.