CLI Overview

Everything you do with flexBlock goes through the single flexblock binary. Each command moves a volume from one lifecycle state to the next, and each refuses with a specific exit code when the state it needs is missing.

Synopsis

flexblock [--ascii] [--log-level FILTER] [--grant-file PATH] <command> [flags]
flexblock --version

Global flags can appear before or after the command name.

Global flags

Flag	Default	Description
`--ascii`	—	Draw output in ASCII only, as a non-UTF-8 locale does.
`--grant-file <PATH>`	`/etc/flexblock/grant.json`	Signed license grant file.
`-h`, `--help`	—	Print help. `--help` gives the long form.
`--log-level <FILTER>`	`info`	A level (`trace`, `debug`, `info`, `warn`, `error`, `off`), or a directive list such as `flexblock=debug,aws_sdk_s3=warn`.
`-V`, `--version`	—	Print the version.

Commands

Command	What it does	Device access	Needs a current grant
`attach <DEVICE>`	Size a cache on this host’s device from the volume superblock and claim ownership. Nothing is bulk-copied.	Write	No
`detach <DEVICE>`	Release ownership and clear local state. The volume’s data is left intact.	Write	No
`init`	Create a new, empty volume in object storage. Refuses a prefix that holds any key other than probe leftovers.	Write, only with `--attach`	Yes
`licenses`	List the open-source dependencies compiled in.	None	No
`reap <ID>...`	Remove leaked or stale ublk kernel devices by id.	Root	No
`show [DEVICE]`	Print device, volume, ownership and connection state. Lock-free, safe against a live daemon.	Read	No
`start <DEVICE>`	Preflight, recover, rebuild the object index, bring up `/dev/ublkbN` and serve until interrupted. Also the crash-recovery command.	Write, and root	No (serves throttled)
`update <DEVICE>`	Change device size, compression or encryption on the volume superblock, then locally. With no change, repairs a missing or stale volume superblock.	Write	Only for `--device-size`
`wipe [DEVICE]`	Delete every object under the prefix and the local cache. Prompts.	Write, when a device is given	No

An expired grant still reaches the volume: start serves throttled, and attach, detach and wipe work. Only init and update --device-size need a current grant. See Licensing.

Where the volume lives

No command takes a bucket, prefix, endpoint or credentials. The volume’s provider, bucket and prefix always come from the grant, and credentials come from the provider’s standard chain (see Credentials).

Output conventions

Progress and outcome reports from state-changing commands go to stderr.
show and licenses write their output, prose or JSON, to stdout, so you can pipe or redirect it.
Every command exits with a documented exit code, so scripts and systemd can tell a transient failure from one that a retry will not fix.
Nearly every state-changing command needs root, so examples use sudo.

Sizes and durations

Sizes accept the suffixes K, M, G, T, P and E, optionally followed by B or iB. All are binary units, so 2T means 2 TiB.

Durations are a whole number followed by s, m, h or d, for example 5s, 4m, 24h or 7d.