czctl CLI Reference

czctl is the management CLI for Control Zero Self-Managed deployments. It is installed alongside the backend container during setup and provides commands for installation, operations, backups, and troubleshooting.

czctl is not available in SaaS deployments. All commands run on the host where Control Zero is installed and require access to the Docker socket and the installation directory (default: /opt/controlzero).

Command Reference

Command	Description
czctl init	Interactive first-time setup wizard. Generates .env file, TLS certs, runs preflight checks. Use --quickstart for zero-question setup with all defaults.
czctl status	Service health summary. Shows status of all Control Zero services, database health, and license info.
czctl preflight	Pre-deployment checks. Verifies the host environment meets requirements before installation.
czctl postflight	Post-deployment health checks. Validates all services are running and healthy after install or upgrade.
czctl upgrade	Upgrade Control Zero to the latest version. Pulls latest container images, creates a pre-upgrade backup, and restarts services.
czctl rollback	Roll back to the most recent pre-upgrade backup. Finds the most recent backup and restores from it.
czctl diagnostics	Run diagnostic tests against running services. Functional tests against a live deployment.
czctl set-log-level <level>	Set the application log level (trace, debug, info, warn, error). Takes effect within 60 seconds.
czctl set-log-retention <days>	Set the number of days to retain audit logs before automatic cleanup.
czctl update-license <key>	Update the license key and restart the backend. Replaces CZ_LICENSE_KEY in .env and restarts the backend container.
czctl rotate-master-key	Re-encrypt all secrets with a new master key passphrase. Rotates the master encryption key.
czctl bootstrap-admin	Create the initial admin user for a fresh deployment.
czctl reset-password	Reset a user password by updating the bcrypt hash in the users table.
czctl backup	Create an encrypted backup archive. Backs up the secrets database, the audit log store, and the rate-limit cache.
czctl restore	Restore from a backup archive.
czctl support-bundle	Collect logs and diagnostics into a bundle for support.
czctl generate-ca	Generate a certificate authority for TLS.
czctl postgres tls provision	Provision industry-standard TLS on a self-managed PostgreSQL box (ECDSA P-256 CA + dual-SAN leaf, TLS 1.3, verify-full, non-breaking cutover). See Secure PostgreSQL with TLS.
czctl postgres tls verify	Prove TLS is in force: a real sslmode=verify-full handshake plus a pg_stat_ssl assertion (a plaintext canary is not proof).

Common Command Examples

Check service health

czctl status

Example output:

Control Zero Self-Managed v1.3.0

Services:
  backend         running  healthy  port 8080
  gateway         running  healthy  port 8443
  dashboard       running  healthy  port 443
  secrets-db      running  healthy
  audit-store     running  healthy
  ratelimit-cache running  healthy

Database:
  Audit records: 142,301
  Oldest record: 2026-01-02T00:00:00Z

License:
  Key:    czs_xxxx...xxxx
  Plan:   Enterprise
  Seats:  100
  Valid until: 2027-04-01

Run an upgrade

czctl upgrade

The upgrade command automatically:

1. Creates a pre-upgrade backup to /opt/controlzero/backups/
2. Runs preflight checks for the new version
3. Pulls updated container images
4. Stops current services
5. Applies any database migrations
6. Starts services with the new version
7. Runs postflight checks

To preview what the upgrade will do without making changes:

czctl upgrade --dry-run

To check if a newer version is available without upgrading:

czctl upgrade --check

Roll back after a failed upgrade

# Roll back to the most recent pre-upgrade backup (auto-finds it in ./backups)
czctl rollback

# Roll back from a specific backup directory
czctl rollback --backup-dir /opt/controlzero/backups

# Preview what would be restored without doing it
czctl rollback --dry-run

# Verify everything is healthy after rollback
czctl postflight

Create and restore backups

# Create a backup
czctl backup

# Backup saved to: /opt/controlzero/backups/cz-backup-<timestamp>.tar.gz

# Restore from a backup
czctl restore --from /opt/controlzero/backups/cz-backup-20260415-083000.tar.gz

Backups include the secrets database, the immutable audit trail, and the rate-limit cache state. Backup archives are encrypted at rest.

Update the license key

czctl update-license czs_your_new_license_key_here

The command replaces CZ_LICENSE_KEY in the active .env file and restarts the backend container. No other services are restarted.

Common Workflows

First-time setup

# 1. Set your license key
export CZ_LICENSE_KEY=czs_your_license_key_here

# 2. Run the interactive setup wizard (or --quickstart for zero-question defaults)
czctl init --quickstart

# 3. Start services
docker compose up -d

# 4. Verify everything is healthy
czctl postflight

# 5. Create the initial admin user
czctl bootstrap-admin

The --quickstart flag uses sensible defaults (gateway on 8443, API on 8080, dashboard on 443, log level info, 90-day audit log retention). To customize interactively instead, run czctl init without the flag.

Upgrading to a new version

# 1. Confirm the current deployment is healthy
czctl postflight

# 2. Check what version is available (optional dry-run)
czctl upgrade --dry-run

# 3. Run the upgrade (creates backup automatically)
czctl upgrade

# 4. Confirm the new version is healthy
czctl postflight

The upgrade creates a pre-upgrade backup automatically. If postflight fails after the upgrade, proceed with the rollback workflow below.

Recovering from a failed upgrade

# 1. Roll back to the pre-upgrade backup automatically
czctl rollback

# Or restore from a specific archive
czctl restore --from /opt/controlzero/backups/cz-backup-<timestamp>.tar.gz

# 2. Confirm the restored deployment is healthy
czctl postflight

# 3. Collect a support bundle before opening a support ticket
czctl support-bundle

The restore command stops all services, reverts configuration and data from the backup archive, reverses any database migrations applied during the upgrade, then restarts services at the previous version.

Rotating credentials

# Rotate the master encryption key (prompts for new passphrase)
czctl rotate-master-key

# Update the license key
czctl update-license czs_new_key_here

# Regenerate TLS certificates (useful at expiry or when changing domains)
czctl generate-ca --domain api.yourdomain.com --output config/certs/

# After regenerating certs, restart the services that use them
docker compose restart gateway backend

After rotating the master key, all secrets stored in the vault are re-encrypted with the new key. The operation is atomic: if it fails partway through, the original key is preserved and no data is lost.

Related

• czctl Admin Commands: Detailed syntax, flags, and security notes for init, bootstrap-admin, reset-password, rotate-master-key, update-license, set-log-level, set-log-retention, support-bundle, and generate-ca.
• Preflight and Postflight Checks: Full reference for all checks run by czctl preflight and czctl postflight.
• Upgrade and Rollback: Detailed upgrade procedures including zero-downtime options.
• Licensing: License key management and renewal.
• Security Hardening: Hardening steps for production deployments.
• Troubleshooting: Common issues and how to resolve them.