CLI Reference

Complete reference for the flo command-line interface.

Global Options

Flag	Description
`--host <addr>`	Server address (default: `localhost:9000`)
`--namespace <name>`	Namespace for operations (default: `default`)
`--timeout <ms>`	Operation timeout in milliseconds
`--format <fmt>`	Output format: `text`, `json`
`--debug`	Enable debug output

Server

`flo server start`

Start a Flo server.

flo server start [options]

Flag	Description	Default
`-c, --config <path>`	Config file path	`flo.toml`
`--port <port>`	Client protocol port	`9000`
`--data-dir <path>`	Data directory	`./data`
`--shard-count <n>`	Number of shard threads	CPU count
`--node-id <id>`	Unique node identifier	auto
`--seeds <addrs>`	Cluster seed addresses	—

`flo server status`

Show server status and health.

flo server status

KV

`flo kv set`

Set a key-value pair.

flo kv set <key> <value> [options]

Flag	Description
`--ttl <seconds>`	Time-to-live
`--if-not-exists`	Only set if key doesn't exist
`--cas <version>`	Compare-and-swap version

`flo kv get`

Get a value by key.

flo kv get <key> [options]

Flag	Description
`--block <ms>`	Block until key appears

`flo kv mget`

Get many keys in a single round trip. Keys may live on different shards — the server gathers results in parallel.

flo kv mget <key1> <key2> ... [options]

Flag	Description
`--namespace <ns>`	Override default namespace
`--output <fmt>`	`text` (default), `json`, or `table`

Maximum 256 keys per call. Missing keys are returned as nil entries (not errors).

`flo kv delete`

Delete a key.

flo kv delete <key> [options]

Flag	Description
`--cas <version>`	Only delete if the current version matches (race-free lock release)
`-r, --routing-key <key>`	Explicit shard routing key
`-t, --txn <id>`	Buffer inside a transaction

`flo kv list`

List keys by prefix.

flo kv list [prefix] [options]

Flag	Description
`--limit <n>`	Maximum number of keys
`--keys-only`	Only return keys, not values

`flo kv history`

Show version history for a key.

flo kv history <key> [options]

Flag	Description
`--limit <n>`	Maximum versions to return

`flo kv incr`

Atomically increment an i64 counter.

flo kv incr <key> [--by <delta>]

Flag	Description
`-b, --by <n>`	Signed delta (default `+1`)

`flo kv touch` / `flo kv persist`

Adjust the TTL on an existing key without rewriting the value.

flo kv touch <key> --ttl <seconds>   # update TTL (0 clears it)
flo kv persist <key>                  # clear TTL

Flag	Description
`--cas <version>`	Only update if the current version matches (race-free lease renewal)
`-r, --routing-key <key>`	Explicit shard routing key
`-t, --txn <id>`	Buffer inside a transaction

`flo kv exists`

Existence check (no value transferred). Exits 0 when present, 1 when absent.

flo kv exists <key>

`flo kv jget` / `jset` / `jdel`

JSON sub-field operations using a small JSONPath subset ($, .field, [index]).

flo kv jset <key> <path> <json>
flo kv jget <key> [path]
flo kv jdel <key> [path]

jget prints both the value and the document's current version; jset / jdel print the new version after the write.

`flo kv begin` / `commit` / `rollback`

Per-shard transactions buffer multiple writes on a single pinned partition and commit them atomically as one Raft entry.

flo kv begin <routing-key>             # → prints txn_id and pinned_hash
flo kv commit <txn-id>                 # → prints commit_index and op_count
flo kv rollback <txn-id>               # discard buffered ops

Add --txn <id> to any of set, get, delete, incr, touch, persist, exists to run that operation inside the transaction:

TXN=$(flo kv begin user:42 --format json | jq -r .txn_id)
flo kv set  user:42:name "Jane" --txn "$TXN"
flo kv incr user:42:visits      --txn "$TXN"
flo kv commit "$TXN"

Every key inside a transaction must hash to the same partition as the routing key, otherwise the server returns kv_txn_cross_shard. scan, mget, jget, jset, jdel, and history are not supported inside transactions.

Server caps: 256 ops per transaction, 1 MiB total payload, 1024 open transactions per server. Transactions survive across stateless connections — they are owned by txn_id, not by the TCP connection.

Streams

`flo stream create`

Create a stream.

flo stream create <name> [options]

Flag	Description
`--retention <duration>`	Retention period (e.g., `7d`, `24h`)
`--max-size <bytes>`	Maximum stream size

`flo stream append`

Append a record to a stream.

flo stream append <stream> <data>

`flo stream read`

Read records from a stream.

flo stream read <stream> [options]

Flag	Description
`--offset <n>`	Start offset
`--count <n>`	Number of records
`--follow`	Follow mode (block for new records)

`flo stream info`

Show stream metadata.

flo stream info <stream>

`flo stream delete`

Delete a stream and all its data (records, metadata, and name registry). Aliased as flo stream rm.

flo stream delete <name> [--force]

Flag	Description
`--force`, `-f`	Delete even if the stream is not empty

Deleting a missing stream is a no-op (idempotent). A non-empty stream is refused unless --force is given. Deleting a stream also deletes that stream's consumer groups (a same-named group on another stream is unaffected). To drop only records while keeping the stream, use flo stream trim.

`flo stream group`

Manage consumer groups. A group is scoped to a single stream — every subcommand takes the <stream> it operates on, and wildcard/fan-in reads (events.*) are not supported.

flo stream group create <stream> --group <name> [--ack-timeout <ms>] [--max-deliver <n>]
flo stream group read   <stream> --group <name> --consumer <id> [--limit <n>] [--block <ms>] [--no-ack]
flo stream group ack    <stream> --group <name> --ids <id,...> [--consumer <id>]
flo stream group nack   <stream> --group <name> --ids <id,...> [--delay <ms>]
flo stream group touch  <stream> --group <name> --consumer <id> --ids <id,...> [--extend <ms>]
flo stream group pending <stream> --group <name> [--consumer <id>]
flo stream group info   <stream> --group <name>
flo stream group join   <stream> <group> <consumer>
flo stream group leave  <stream> --group <name> --consumer <id>
flo stream group delete <stream> --group <name>

Queues

`flo queue enqueue`

Add a message to a queue.

flo queue enqueue <queue> <data> [options]

Flag	Description
`--priority <n>`	Message priority (higher = sooner)
`--delay <ms>`	Delivery delay in milliseconds
`--dedup-key <key>`	Deduplication key

`flo queue dequeue`

Dequeue messages.

flo queue dequeue <queue> [options]

Flag	Description
`--count <n>`	Number of messages (default: 1)
`--block <ms>`	Block until messages available
`--visibility <ms>`	Visibility timeout for leased messages

`flo queue ack`

Acknowledge processed messages.

flo queue ack <queue> <sequence...>

`flo queue nack`

Negative acknowledge (requeue or send to DLQ).

flo queue nack <queue> <sequence...> [options]

Flag	Description
`--dlq`	Send to dead-letter queue

`flo queue peek`

Peek at messages without leasing.

flo queue peek <queue> [--count <n>]

`flo queue dlq`

Manage dead-letter queue.

flo queue dlq list <queue> [--count <n>]
flo queue dlq requeue <queue> <sequence...>
flo queue dlq purge <queue>

Time-Series

`flo ts write`

Write a data point using InfluxDB line protocol.

flo ts write <measurement> <tags> <fields>

Examples:

flo ts write cpu host=web-01 usage=82.5
flo ts write temperature region=us-east,sensor=a1 value=23.4

`flo ts query`

Run a FloQL query.

flo ts query "<query>"

Examples:

flo ts query "cpu{host=web-01}[1h] | avg(5m)"
flo ts query "temperature{region=us-east}[24h] | max(1h)"

Actions

`flo action register`

flo action register <name> [options]

Flag	Description
`--timeout <ms>`	Execution timeout
`--max-retries <n>`	Maximum retry count

`flo action invoke`

Invoke an action.

flo action invoke <name> [data] [options]

Flag	Description
`--idempotency-key <key>`	Dedup key for at-most-once
`--priority <n>`	Execution priority
`--wait`	Wait for completion

`flo action status`

Check action execution status.

flo action status <run-id>

Workflows

`flo workflow create`

Create a workflow from a YAML definition.

flo workflow create -f <file.yaml>

`flo workflow start`

Start a workflow execution.

flo workflow start <name> [data]

`flo workflow status`

Check workflow execution status.

flo workflow status <execution-id>

`flo workflow signal`

Send a signal to a running workflow.

flo workflow signal <execution-id> <signal-name> [data]

Processing

`flo processing submit`

Submit a stream processing job.

flo processing submit -f <job.yaml>

`flo processing status`

Check job status.

flo processing status <job-id>

`flo processing stop`

Stop a running job.

flo processing stop <job-id>

Cluster

`flo cluster status`

Show cluster membership and partition distribution.

flo cluster status

`flo cluster rebalance`

Trigger partition rebalancing.

flo cluster rebalance

← Previous

Clustering

Web Console

Edit this page on GitHub

CLI Reference

Global Options

Server

flo server start

flo server status

KV

flo kv set

flo kv get

flo kv mget

flo kv delete

flo kv list

flo kv history

flo kv incr

flo kv touch / flo kv persist

flo kv exists

flo kv jget / jset / jdel

flo kv begin / commit / rollback

Streams

flo stream create

flo stream append

flo stream read

flo stream info

flo stream delete

flo stream group

Queues

flo queue enqueue

flo queue dequeue

flo queue ack

flo queue nack

flo queue peek

flo queue dlq