CLI reference

The flux CLI is the operator interface for provisioning, migrations, lifecycle, backups, and private database access.

What you will learn

How to discover commands locally
Common verbs and their intent
Relationship to dashboard operations

The idea

Exact flags evolve—flux --help and subcommand help are authoritative for your installed version. This page orients you; it does not duplicate every flag (that belongs in --help and release notes).

Common commands

Command	Purpose
`flux login`	Verify API token / base URL
`flux init`	Link or create a project from repo-root `flux.json` (Foundry placeholder hash)
`flux create`	Provision a project
`flux list`	Show projects and Service URLs
`flux push`	Apply a `.sql` file or ordered `migrations/` directory—`--mode raw\|versioned\|repeatable`, `--force` (repeatable), `--plan` / `--dry-run` preview directory pushes; pass `--project` / `--hash` (or `flux.json`)
`flux migrations list`	Show `flux.flux_migrations` ledger (remote state, not local files). `flux migrations` ≠ `flux migrate` (engine conversion)
`flux project credentials`	v1 dedicated → structured Postgres block (user, password, host, port, connection URL) plus anon/service JWT keys. v2_shared → gateway JWT secret and a short note. Use `--field postgres.password` (v1) for paste-friendly password-only output
`flux db password`	v1 dedicated → print only the Postgres password. v2_shared → explains temporary tunnel credentials (never pooled admin secrets)
`flux db tunnel`	Open local SSH tunnel; print GUI connection settings. v1 → password via `flux db password`. v2 → creates temporary scoped credentials when opening the tunnel
`flux db shell`	`psql` through the tunnel; `--command 'SELECT 1'` for non-interactive queries
`flux db dump`	v2_shared schema-scoped `pg_dump` via tunnel; use `--schema-only` with readonly temp roles when RLS blocks data
`flux db restore`	v1 dedicated `pg_restore` via tunnel (restore-verified backup gate). v2_shared refused for production pooled schemas
`flux db access-plan` / `flux db gui-config`	Redacted mode-aware metadata and copy-friendly GUI fields
`flux dump`	Legacy project export (see flags locally; distinct from `flux db dump`)
`flux migrate`	Orchestrate v2_shared → v1_dedicated via the control plane (see Pooled → dedicated migrate)
`flux logs`	Tail project logs when wired
`flux backup create`	Both engines — control plane streams `pg_dump -Fc`. v1: full project DB. v2: tenant API schema (`--schema=t_<short>_api --no-owner --no-acl`). See Backups workflow
`flux backup list`	Recent backups newest-first with trust labels (Restorable / Created, not restore-verified / Restore verification failed / etc.). Pass `--verbose` for catalog timestamps, artifact paths, and underlying tier names
`flux backup verify`	Runs `pg_restore` in a disposable Postgres container on the control plane. The only step that promotes a backup to Restorable. Requires `docker-cli` in the `flux-web` image (self-hosted operators)
`flux backup download`	Writes the custom-format archive to `-o <path>` (or shell redirect). Refuses binary output to a TTY

Private database access: Private database access guide — SSH tunnels, Beekeeper/DBeaver setup, password handoff.

Operators (v2_shared): If directory flux push fails on a legacy global migration ledger, run bin/migrate-pooled-ledger.sh on the Flux host — see Migrations workflow and the root README.

Identifiers

Codex / internal docs describe hashing:

Resource pattern: flux-{hash}-{slug} (7-char hex hash segment)
Slug is user-facing; hash is assigned at provision time

The same Codex contract JSON is available from the dashboard at GET /api/cli/v1/codex (useful for assistants and tooling).

How it works

Install: Installation.

Foundry / app repo workflow

When the repo already has flux.json with "hash": "REPLACE_AFTER_FLUX_INIT":

bash

flux loginflux initpnpm flux:schema:syncflux push sql/migrations/ --plan

flux init writes the control-plane slug, hash, and optional apiUrl / mode / apiSchema into flux.json. It does not write JWT or gateway secrets—use flux project credentials or the dashboard for those.

Example