cli

The xs CLI provides a collection of subcommands for interacting with a cross.stream store.

Usage

xs <COMMAND> [OPTIONS]

Commands

• serve – Provides an API to interact with a local store
• cat – cat the event stream
• append – Append an event to the stream
• cas – Retrieve content from Content-Addressable Storage
• cas-post – Store content in Content-Addressable Storage
• remove – Remove an item from the stream
• head – Get the head frame for a topic
• get – Get a frame by ID
• import – Import a frame directly into the store
• exec – Execute a Nushell script with store helper commands available
• version – Get the version of the server
• nu – Manage the embedded xs.nu module
• scru128 – Generate and manipulate SCRU128 IDs

serve

Start the supervisor process.

xs serve <path> [--expose <LISTEN_ADDR>]

Option	Description
<path>	Path to the store
--expose <LISTEN_ADDR>	Expose the API on an additional address ([HOST]:PORT, <PATH>, or iroh://)

Examples:

# Expose on TCP port
xs serve ./store --expose 127.0.0.1:8080

# Expose via iroh for peer-to-peer QUIC connections
xs serve ./store --expose iroh://

See the Exposing Streams reference for detailed networking options.

cat

Stream frames from the store.

xs cat <addr> [options]

Option	Description
<addr>	Address to connect to ([HOST]:PORT, <PATH>, or iroh://...)
--follow, -f	Follow the stream for new events
--pulse <ms>, -p <ms>	Send synthetic xs.pulse events at interval
--tail, -t	Begin reading from the end of the stream
--last-id <id>, -l <id>	Start after the given frame ID
--limit <n>	Maximum number of events to return
--sse	Use Server-Sent Events format
--context <id>, -c <id>	Context ID (defaults to system context)
--all, -a	Retrieve frames across all contexts
--topic <topic>, -T <topic>	Filter frames by topic

Examples:

# Local store
xs cat ./store --follow

# Remote TCP connection
xs cat :3021 --follow

# Peer-to-peer via iroh QUIC
xs cat iroh://nodeac4lrf7r5hyq...crjpx6ajinb2hi4d --follow

See Exposing Streams reference for connection details.

append

Append an event to a topic.

xs append <addr> <topic> [options]

Option	Description
<addr>	Address to connect to
<topic>	Topic to append to
--meta <json>	JSON metadata to include
--ttl <ttl>	Time-to-live: forever, ephemeral, time:<ms>, head:<n>
--context <id>, -c <id>	Context ID (defaults to system context)

Example:

echo "hello" | xs append ./store chat --meta '{"user":"bob"}'

cas

Retrieve content from CAS.

xs cas <addr> <hash>

Option	Description
<addr>	Address to connect to ([HOST]:PORT, <PATH>, or iroh://...)
<hash>	Hash of the content to retrieve

cas-post

Store content in CAS.

xs cas-post <addr>

Option	Description
<addr>	Address to connect to

Example:

echo "content" | xs cas-post ./store

remove

Remove a frame from the store.

xs remove <addr> <id>

Option	Description
<addr>	Address to connect to
<id>	ID of the item to remove

head

Get the most recent frame for a topic.

xs head <addr> <topic> [--follow]

Option	Description
<addr>	Address to connect to
<topic>	Topic to inspect
--follow, -f	Follow for updates
--context <id>, -c <id>	Context ID (defaults to system context)

get

Retrieve a frame by ID.

xs get <addr> <id>

Option	Description
<addr>	Address to connect to
<id>	ID of the frame to get

import

Import a frame dump from standard input.

xs import <addr>

Option	Description
<addr>	Address to connect to

Example:

cat dump.jsonl | xs import ./store

exec

Execute a Nushell script with store helper commands available.

xs exec <addr> <script>

Option	Description
<addr>	Address to connect to ([HOST]:PORT, <PATH>, or iroh://...)
<script>	Nushell script to execute, or ”-” to read from stdin

The exec command runs a Nushell script with access to store helper commands like .cat, .append, .head, .get, .cas, and .remove.

Output format auto-detection:

• ByteStream → raw bytes
• ListStream of structured data → JSONL stream
• ListStream of primitives → JSONL stream
• ListStream of mixed types → JSONL stream
• Single Value (string/number) → raw text
• Single structured Value → single JSON object
• PipelineData::Empty → nothing

Examples:

# Simple expression
xs exec ./store '"hello world"'

# Math expression
xs exec ./store '2 + 3'

# JSON output
xs exec ./store '{name: "test", value: 42}'

# Script from stdin
echo '"from stdin"' | xs exec ./store -

# Using store helpers
xs exec ./store '"my note" | .append note'
xs exec ./store '.head note'
xs exec ./store '.cat --topic note'

version

Get version information from the server.

xs version <addr>

Option	Description
<addr>	Address to connect to

nu

Manage the embedded xs.nu module.

xs nu [--install] [--clean]

Option	Description
--install	Install xs.nu into your Nushell config
--clean	Remove previously installed files

Without options the command prints the module contents so it can be redirected or piped.

Example:

xs nu --install

The xs.nu module provides Nushell-friendly convenience functions that wrap these CLI commands with pipeline support and environment awareness. The module automatically uses $env.XS_ADDR when connecting to remote stores.

See the xs.nu reference for detailed documentation of all available functions and the Exposing Streams reference for remote connection setup.

scru128

Generate and manipulate SCRU128 IDs. SCRU128 is a sortable, clock and random number-based unique identifier.

xs scru128 [COMMAND]

Generate a new ID

Generate a single SCRU128 ID:

xs scru128

Example:

xs scru128
# => 03d4q1qhbiv09ovtuhokw5yxv

unpack

Unpack a SCRU128 ID into its component fields:

xs scru128 unpack <ID>

Option	Description
<ID>	SCRU128 ID string, or - to read from stdin

The output is a JSON object with the following fields:

• timestamp - Unix timestamp as float (milliseconds precision)
• counter_hi - 24-bit high counter value
• counter_lo - 24-bit low counter value
• node - 32-bit entropy/node field as hex string

Examples:

xs scru128 unpack 03d4q1qhbiv09ovtuhokw5yxv
# =>
# {
#   "timestamp": 1693000000.123,
#   "counter_hi": 1234,
#   "counter_lo": 5678,
#   "node": "abcd1234"
# }

echo "03d4q1qhbiv09ovtuhokw5yxv" | xs scru128 unpack -

pack

Pack component fields into a SCRU128 ID:

xs scru128 pack

Reads a JSON object from stdin with the same format as unpack output.

Example:

echo '{"timestamp":1693000000.123,"counter_hi":1234,"counter_lo":5678,"node":"abcd1234"}' | xs scru128 pack
# => 03d4q1qhbiv09ovtuhokw5yxv

Round-trip example:

xs scru128 | xs scru128 unpack | xs scru128 pack