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 [email protected] --display-name "You"

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

createsuperuser

z4j createsuperuser --email [email protected] --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 [email protected] --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 [email protected]
z4j reset-mfa [email protected] --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.

Schedules

misfires

z4j misfires --project my-app
z4j misfires --project my-app --limit 200
z4j misfires --project my-app --json

Lists a project’s detected schedule misfires across ALL of its schedules, newest first. A misfire is a system-detected “this enabled interval or cron schedule missed its expected slot past the grace window” event, recorded by the brain’s misfire detector (see misfire detection). The default output is an aligned text table (schedule id, detected-at, name, engine, kind, lateness, grace); --json emits {"project": <slug>, "misfires": [...]} for scripting. --limit defaults to 50 and is capped at 1000. This is the shell-side twin of the VIEWER-facing GET /api/v1/projects/{slug}/schedules/misfires endpoint, so an operator can triage missed slots without the dashboard. Exit 0 on success (including an empty history); exit 2 on a bad slug, unknown project, or unreachable 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                       # local introspection: version + configured brain URLs + mode (no network)
z4j-scheduler info [--json]                # live runtime snapshot from the running scheduler's GET /info
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.