nova CLI reference

Every nova command, subcommand, flag, environment variable, and default, as printed by --help

The complete nova command tree. Flags, env vars, and defaults are copied from nova … --help; a flag marked required is enforced by the command even where the help text does not say so. For a task-oriented walkthrough see using nova.

nova [global options] [command [command options]]

Global options

Global options go before the command. Every verb that dials the cluster requires --addr; token mint and credential generate run offline and ignore it.

Flag	Env	Default	Meaning
`--addr`	`NOVA_ADDR`	—	`novad` address; all services share one port
`--token`	`NOVA_TOKEN`	—	Bearer token (JWT), presented on both planes
`--tls-ca`	`NOVA_TLS_CA`	—	CA bundle verifying the server; enables TLS
`--tls-cert`	`NOVA_TLS_CERT`	—	Client certificate for mutual TLS
`--tls-key`	`NOVA_TLS_KEY`	—	Client key for mutual TLS
`--admin-user`	`NOVA_ADMIN_USER`	—	Admin basic-auth username; when set, basic auth replaces the bearer on the admin plane
`--admin-password`	`NOVA_ADMIN_PASSWORD`	—	Admin basic-auth password

TLS resolution: a client certificate or key selects mutual TLS (with --tls-ca as the server CA); a CA alone selects server-verified TLS; nothing selects plaintext.

Arguments

Form	Accepted by	Meaning
`nova://bucket/key`	every stream verb	Bucket up to the first `/`, key everything after it, verbatim
`name` or `nova://name`	`bucket` verbs, `ls`	A bucket

Exit codes

Code	Meaning
`0`	Success
`1`	The command ran and failed; the error prints as `nova: <error>` on stderr
`2`	Flag, usage, or unknown-command error (including a missing `--addr`)

ls

nova ls [options] [bucket | nova://bucket]

Lists buckets when given no argument; lists a bucket's streams (nova://bucket/key class per line) when given one. A bucket/key path is refused. Prints next: … when another page exists.

Flag	Default	Meaning
`--limit`	`100`	Page size
`--cursor`	—	Resume after this bucket name (buckets) or at the printed cursor (streams)

bucket

Bucket lifecycle: the container every stream is created in.

bucket create

nova bucket create [options] <name | nova://name>

Flag	Default	Meaning
`--location`	—	Opaque location metadata
`--create-on-append`	`false`	Appends to a missing stream create it with the bucket's defaults
`--create-on-read`	`false`	Reads of a missing stream create it (empty) with the bucket's defaults
`--default-class`	`standard`	Default stream class: `standard` or `express`

Prints the name, then one line with location, create-on-append, create-on-read, default-durability (the default class), and created.

bucket get

nova bucket get <name | nova://name>

No options. Prints the same config line as bucket create.

bucket list

nova bucket list [options]

Flag	Default	Meaning
`--limit`	`100`	Page size
`--cursor`	—	Resume after this bucket name

One name per line; next: -cursor <name> when another page exists.

bucket delete

nova bucket delete <name | nova://name>

No options. Removes the bucket only when no streams live in it.

stream

Stream lifecycle.

stream create

nova stream create [options] [nova://bucket/key]

A positional address wins over --bucket/--key. A flag left out stays unset and the bucket's defaults fill it at the server. The bucket is created-or-joined by convention before the stream is created.

Flag	Default	Meaning
`--class`	bucket default	`standard` (chained to standard object storage) or `express` (fanout to express-class buckets)
`--producer`	bucket default	`any` or `fenced` (fencing tokens enforced)
`--retention-max-age`	bucket default	Retention age bound (a duration such as `168h`)
`--throughput`	bucket default	Max append bytes/second
`--bucket`	`default`	The containing bucket
`--key`	a generated UUID	The stream's key within the bucket

Prints nova://bucket/key, then a line with durability (the class), producer, retention-max-age, throughput, and the minted id.

stream get

nova stream get <nova://bucket/key>

No options. Prints the stream's configuration line.

stream list

nova stream list [options]

Flag	Default	Meaning
`--limit`	`100`	Page size (server-capped at 1000)
`--cursor`	—	Resume at the cursor the prior page printed
`--bucket`	`default`	The bucket to list (listings are per bucket)

stream reconfigure

nova stream reconfigure [options] nova://bucket/key

Changes only the fields named by a flag; a flag left out stays as it is, and a flag given as zero sets zero (--retention-max-age 0 is unbounded, --throughput 0 unlimited). At least one flag is required. Retention applies at once; the other fields reach the stream through a handoff of its leadership, so a live producer reconnects once.

Flag	Default	Meaning
`--class`	unchanged	`standard` or `express`; a live stream hands off to switch
`--producer`	unchanged	`any` or `fenced`
`--retention-max-age`	unchanged	Retention age bound; `0` = unbounded
`--throughput`	unchanged	Max append bytes/second; `0` = unlimited

Prints the address, then the descriptor line stream get prints.

stream delete

nova stream delete <nova://bucket/key>

No options. Tears the stream down.

stream trim

nova stream trim [options] <nova://bucket/key>

Exactly one of the two flags is required.

Flag	Default	Meaning
`--at`	—	Trim everything stamped before this RFC 3339 time
`--entry`	—	Trim everything below this sequence number

append

nova append [options] <nova://bucket/key>

Appends stdin lines as records, one per line (newline stripped; lines over 64 KiB fail). Lines pipeline through one producer session; through a Gateway, and with no fencing token, they fall back to sequential one-shot batches of at most 1000 records or 1 MiB. Prints appended N entries, the acknowledged count.

Flag	Default	Meaning
`--fencing-token`	—	Present a fencing token (exact match against what `fence` installed)
`--linger`	`5ms`	Max wait for a fuller batch (`0` cuts immediately)

tail

nova tail [options] <nova://bucket/key>

Shows the stream's last records, oldest first: the window [tail−n, tail), clamped to the earliest record retention still holds.

Flag	Default	Meaning
`--limit`, `-n`	`10`	How many trailing records to show
`--follow`, `-f`	`false`	Keep following the tail (Subscribe) from the window's start

check-tail

nova check-tail <nova://bucket/key>

No options. Prints the committed tail (one past the last record) and the last record's time, tab-separated: 6 2026-08-24T10:01:12Z.

fence

nova fence <nova://bucket/key> [token]

No options. With a token: installs or rotates the stream's fencing token and prints fenced "<token>" boundary <seq>. Without one: clears it and prints cleared boundary <seq>. The boundary is the admission tail at which the change took effect.

read

nova read [options] <nova://bucket/key>

Prints records as seq_num, RFC 3339 timestamp, body, tab-separated, one per line.

Flag	Default	Meaning
`--from`	the earliest still-retained record	First sequence number
`--since`	—	First record stamped at or after this RFC 3339 time
`--limit`	`100`	Stop after this many records (ignored with `--follow`)
`--follow`, `-f`	`false`	Keep following the tail (Subscribe)

health

nova health

No options; admin plane. Prints SERVING or DRAINING, then node=<StarID> location=… version=… leading=<count>; a drained star adds drained: safe to decommission.

fleet

nova fleet

No options; admin plane. One line per live star: <StarID> location=… addr=….

node

Node lifecycle: drain and decommission. Admin plane.

node drain

nova node drain [options]

Starts the drain of the star at --addr and echoes its health line.

Flag	Default	Meaning
`--stop`	`false`	Reverse an in-progress drain

node decommission

nova node decommission [options]

Durably declares a star gone forever, through any live star.

Flag	Default	Meaning
`--star` (required)	—	The StarID to declare gone forever
`--force`	`false`	Bypass the drained-target guard (a registered but hung star)
`--cool-down`	`false`	Let the star's settle schedule drain on its own clocks instead of the default force-drain

token

Token verbs: the offline mint and the exchange.

token exchange

nova token exchange [options]

Trades an api-key for a short-lived scoped token, revocable at the credential, unlike anything minted offline. Prints the token alone, pipeable into NOVA_TOKEN.

Flag	Env	Default	Meaning
`--key-id` (required)	—	—	The credential's key id
`--secret`	`NOVA_EXCHANGE_SECRET`	—	The api-key secret; prefer the env over the flag (shell history)
`--bucket`	—	—	The ask: the credential's grants narrowed to this bucket
`--scope`	—	—	The ask: an explicit grant subset (the `nova:` grammar)
`--ttl`	—	`0s`	Token lifetime; zero takes the server default, and the server clamps either way

token mint

nova token mint [options]

Signs a data- or admin-plane JWT offline with a shared HMAC secret (HS256). No address needed.

Flag	Default	Meaning
`--subject` (required)	—	The standard `sub` claim: the caller's audit identity
`--hmac-secret-file` (required)	—	HS256 shared secret (the same file `novad` verifies against)
`--admin`	`false`	Grant the `nova:admin` marker, an operator token
`--ttl`	`24h0m0s`	Token lifetime

credential

Api-key credentials: the registry the exchange mints tokens from. generate is offline; the rest are admin plane.

credential generate

nova credential generate [options]

Mints the root api-key pair offline and emits the boot seed (hash only, never the secret). Exactly one of --seed-out or --env is required. Prints key_id, the secret once, and the seed path or the NOVAD_ROOT_CREDENTIAL='…' line.

Flag	Default	Meaning
`--scope`	`nova:admin`	The credential's grants (the `nova:` grammar; must parse fully valid)
`--seed-out`	—	Where to write the seed file `novad` boots from
`--env`	`false`	Print the seed as the diskless `NOVAD_ROOT_CREDENTIAL` line instead

credential create

nova credential create [options]

Registers an api-key in the running cluster's registry. Prints the key id, the secret exactly once, and the scope.

Flag	Default	Meaning
`--scope` (required)	—	The credential's grants (the `nova:` grammar; must parse fully valid)

credential list

nova credential list [options]

One row per credential: key id, active or disabled, creation time (UTC), scope, tab-separated. next: <key id> when another page exists.

Flag	Default	Meaning
`--cursor`	—	Resume after this key id
`--limit`	`100`	Rows per page

credential revoke

nova credential revoke <key-id>

No options. Disables the credential: exchanges refuse immediately; already-minted tokens live out their TTL.

Source documents

cmd/novactl/main.go, cmd/novactl/commands_cli.go, cmd/novactl/buckets_cli.go, cmd/novactl/token.go, cmd/novactl/credential.go

nova CLI reference

On this page