CLI reference

The brain ships a CLI: z4j-brain. Runs inside the container or from a local pip install.

z4j-brain --help

Serving

`serve`

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

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

Health

`check`

z4j-brain check

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

`status`

z4j-brain 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-brain version

Prints the installed z4j-brain version.

User management

`createsuperuser`

z4j-brain createsuperuser --email [email protected] --display-name "You"
z4j-brain createsuperuser --email [email protected] --display-name "You" --password-stdin

Creates an admin user (Django-style alias for bootstrap-admin). First-boot only - call this once right after pip install z4j or the first container start. Use --password-stdin to pipe the password in from a secret manager.

`bootstrap-admin`

z4j-brain bootstrap-admin --email [email protected] --display-name "You"

Creates the initial admin user and the default project. First-boot only. createsuperuser is the same command under a Django-friendly name.

`changepassword`

z4j-brain changepassword [email protected]
z4j-brain changepassword [email protected] --password-stdin

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

Destructive operations

`reset-setup`

z4j-brain 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-brain reset           # refuses without --force
z4j-brain reset --force

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

Migrations

`migrate`

z4j-brain migrate upgrade head
z4j-brain migrate current
z4j-brain migrate history

Runs an Alembic command against the brain database.

Audit log

`audit verify`

z4j-brain audit verify

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

Global flags

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

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