CLI reference

Every command and flag of wb, as wb <command> --help prints them. The CLI guide explains how to use it.

wb <version>: every database on your server, found and opened.

Usage: wb <command> [arguments] [flags]

Session
  login                Sign in to a Wharfbase server and save the session
  logout               End the CLI session and forget its token
  whoami               Show who the CLI is signed in as
  status               Version, plan, servers, databases and the last scan
  version              Print the CLI version (and the server’s, when reachable)

Discovery
  scan                 Scan for databases now and print what changed
  ls                   List the databases found
  inspect              Everything Wharfbase knows about one database
  topology             Projects, containers and the databases they use
  findings             Security findings across all databases

Data
  connect              Test credentials and save a connection
  dbs                  List the databases on a database server
  tables               List tables, views and collections, with estimates
  describe             Columns, indexes and foreign keys of a table
  query                Run SQL (or a console command) and stream the results
  shell                Open the native client (psql, mysql, mongosh, redis-cli) for a database

Administration
  users                Manage user accounts (admins)
  license              Plan and license key
  doctor               Check the installation; --bundle writes a support zip
  audit                The audit log
  keys                 Master key

Inside the container
  setup-token          Print the first-run setup token (inside the container, before setup)
  healthcheck          Exit 0 when the local server answers /healthz (the Docker HEALTHCHECK)
  relay                Forward TCP port 7000 to host:port (Wharfbase's relay containers run this)

Global flags
  --json               Machine-readable output
  --profile <name>     Use a saved login other than the current one
  --server <id|name>   Limit to one server (multi-server setups)
  --no-color           No colors (also NO_COLOR=1)
  -q, --quiet          No progress output; lists print ids only
  -h, --help           Help for a command

Run `wb <command> --help` for its flags. Exit codes: 0 ok, 1 error, 2 usage,
3 auth, 4 not found, 5 plan limit, 6 unreachable.

Session

wb login

Usage: wb login [url] [flags]

Sign in to a Wharfbase server and save the session

Arguments
  url   Server URL (https://host or host:8480)

Flags
  --email <value>    Account email
  --password-stdin   Read the password from stdin
  --totp <value>     Authentication code (or a recovery code)
  --insecure         Accept a self-signed TLS certificate

Examples
  wb login https://wharfbase.example.com
  printf %s "$PASSWORD" | wb login 10.0.0.5:8480 --email [email protected] --password-stdin

wb logout

Usage: wb logout

End the CLI session and forget its token

wb whoami

Usage: wb whoami

Show who the CLI is signed in as

wb status

Usage: wb status

Version, plan, servers, databases and the last scan

wb version

Usage: wb version

Print the CLI version (and the server’s, when reachable)

Discovery

wb scan

Usage: wb scan [flags]

Scan for databases now and print what changed

Flags
  --deep      Also look inside containers for SQLite files
  --no-wait   Print the scan id and return

wb ls

Usage: wb ls [flags]

List the databases found

Flags
  --engine <value>    Only these engines (comma-separated: postgres,mysql)
  --status <value>    Only these statuses (running, stopped, unreachable, gone)
  --project <value>   Only this compose project
  --findings          Only databases with security findings
  -a, --all           Include hidden and gone databases

Examples
  wb ls
  wb ls --engine postgres,mysql --status running
  wb ls -q

wb inspect

Usage: wb inspect <db>

Everything Wharfbase knows about one database

Arguments
  db   Id (or its start), name, or container name

Examples
  wb inspect pg17
  wb inspect 7kq2m9x4 --json

wb topology

Usage: wb topology [flags]

Projects, containers and the databases they use

Flags
  --dot   Graphviz DOT instead of a tree

Examples
  wb topology
  wb topology --dot | dot -Tsvg > topology.svg

wb findings

Usage: wb findings [flags]

Security findings across all databases

Flags
  --severity <critical|high|medium|low|info>   Only this severity and worse
  --rule <value>                               Only this rule (F001…F014)

Examples
  wb findings
  wb findings --severity high --json

Data

wb connect

Usage: wb connect <db> [flags]

Test credentials and save a connection

Arguments
  db   Id, name, or container name

Flags
  -u, --user <value>                           Database user
  --password-stdin                             Read the password from stdin
  --use-detected-password                      Use the password from the container's environment (audited)
  -d, --database <value>                       Database to open by default
  --remember                                   Save the password (encrypted)
  --read-only                                  Read-only connection
  --label <value>                              A name for the connection
  --tls <disable|prefer|require|verify-full>   TLS mode
  --test                                       Only check the credentials; save nothing

Examples
  wb connect pg17 --user app --use-detected-password --remember
  printf %s "$PW" | wb connect mysql --user root --password-stdin --read-only

wb dbs

Usage: wb dbs <db> [flags]

List the databases on a database server

Arguments
  db   Id, name, or container name

Flags
  --connection <value>   Use this connection (id or its start)
  --password-stdin       Password for a connection that has none saved

wb tables

Usage: wb tables <db> [flags]

List tables, views and collections, with estimates

Arguments
  db   Id, name, or container name

Flags
  -d, --database <value>   Database (default: the connection’s)
  -s, --schema <value>     Schema (PostgreSQL; default public)
  --connection <value>     Use this connection (id or its start)
  --password-stdin         Password for a connection that has none saved

Examples
  wb tables pg17
  wb tables pg17 -d appdb -s audit
  wb tables mongo -d shop

wb describe

Usage: wb describe <db> <table> [flags]

Columns, indexes and foreign keys of a table

Arguments
  db      Id, name, or container name
  table   Table or collection (schema.table works too)

Flags
  -d, --database <value>   Database (default: the connection’s)
  -s, --schema <value>     Schema (PostgreSQL)
  --connection <value>     Use this connection (id or its start)
  --password-stdin         Password for a connection that has none saved

Examples
  wb describe pg17 customers
  wb describe pg17 audit.events --json

wb query

Usage: wb query <db> [sql] [flags]

Run SQL (or a console command) and stream the results

Arguments
  db    Id, name, or container name
  sql   The script; - or nothing reads stdin

Flags
  -d, --database <value>      Database (default: the connection’s)
  --format <table|json|csv>   Output format (default table; --json = json)
  --max-rows <value>          Rows per statement (default 1000)
  --params <value>            Bind parameters as a JSON array, for a one-statement script ($1, ?, @p1 or :1 by engine)
  --connection <value>        Use this connection (id or its start)
  --password-stdin            Password for a connection that has none saved

Examples
  wb query pg17 "SELECT id, name FROM customers LIMIT 5"
  wb query pg17 'SELECT * FROM orders WHERE customer_id = $1' --params '[42]'
  wb query pg17 --format csv "SELECT * FROM orders" > orders.csv
  cat migration.sql | wb query mysql -d appdb
  wb query redis 'HGETALL user:1'

wb shell

Usage: wb shell <db> [flags]

Open the native client (psql, mysql, mongosh, redis-cli) for a database

Arguments
  db   Id, name, or container name

Flags
  -d, --database <value>   Database (default: the connection’s)
  --connection <value>     Use this connection (id or its start)
  --password-stdin         Password for a connection that has none saved

Examples
  wb shell pg17
  docker exec -it wharfbase wb shell mysql -d appdb

Administration

wb users

Usage: wb users <command>

Manage user accounts (admins)

Commands
  ls               List users
  add              Create a user (a temporary password unless one is given)
  reset-password   Give a user a new temporary password (ends their sessions)
  unlock           Clear a lockout after failed sign-ins
  role             Change a user’s role (owner transfers ownership)

wb users ls

Usage: wb users ls

List users

wb users add

Usage: wb users add <email> [flags]

Create a user (a temporary password unless one is given)

Arguments
  email   Email

Flags
  --name <value>                 Display name (default: from the email)
  --role <viewer|editor|admin>   Role
  --password-stdin               Set the password from stdin instead

Examples
  wb users add [email protected] --role editor

wb users reset-password

Usage: wb users reset-password <user>

Give a user a new temporary password (ends their sessions)

Arguments
  user   Email or id

wb users unlock

Usage: wb users unlock <user>

Clear a lockout after failed sign-ins

Arguments
  user   Email or id

wb users role

Usage: wb users role <user> <role> [flags]

Change a user’s role (owner transfers ownership)

Arguments
  user   Email or id
  role   viewer, editor, admin or owner

Flags
  -y, --yes   Transfer ownership without asking

wb license

Usage: wb license <command>

Plan and license key

Commands
  status       The plan, the license and the usage against its limits
  activate     Activate a license key on this instance (- reads it from stdin)
  deactivate   Free this instance’s activation; back to Community

wb license status

Usage: wb license status

The plan, the license and the usage against its limits

wb license activate

Usage: wb license activate <key>

Activate a license key on this instance (- reads it from stdin)

Arguments
  key   The license key

Examples
  wb license activate eyJhbGciOi…
  wb license activate - < license.key

wb license deactivate

Usage: wb license deactivate [flags]

Free this instance’s activation; back to Community

Flags
  --force   Even when the license server can’t be told

wb doctor

Usage: wb doctor [flags]

Check the installation; --bundle writes a support zip

Flags
  --bundle               Write a redacted support bundle (zip)
  -o, --output <value>   Bundle path (- for stdout)

Examples
  wb doctor
  wb doctor --bundle
  docker exec wharfbase wb doctor --bundle -o - > support.zip

wb audit

Usage: wb audit <command>

The audit log

Commands
  verify   Check the audit log’s hash chain
  tail     The latest audit entries; -f keeps following

wb audit verify

Usage: wb audit verify

Check the audit log’s hash chain

wb audit tail

Usage: wb audit tail [flags]

The latest audit entries; -f keeps following

Flags
  -f, --follow          Keep printing new entries
  -n, --lines <value>   How many to start with (default 20)
  --action <value>      Only this action (sql.executed, auth.login…)

Examples
  wb audit tail -n 50
  wb audit tail -f --action sql.executed

wb keys

Usage: wb keys <command>

Master key

Commands
  rotate   Replace the master key and re-seal every stored secret (inside the container)

wb keys rotate

Usage: wb keys rotate [flags]

Replace the master key and re-seal every stored secret (inside the container)

Flags
  -y, --yes   Do not ask for confirmation

Examples
  docker exec -it wharfbase wb keys rotate

Inside the container

wb setup-token

Usage: wb setup-token

Print the first-run setup token (inside the container, before setup)

wb healthcheck

Usage: wb healthcheck

Exit 0 when the local server answers /healthz (the Docker HEALTHCHECK)

wb relay

Usage: wb relay [flags]

Forward TCP port 7000 to host:port (Wharfbase's relay containers run this)

Flags
  --to <value>   The database: host:port