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
• version – Get the version of the server
• nu – Manage the embedded xs.nu module

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 or <PATH>)

Example:

xs serve ./store --expose 127.0.0.1:8080

cat

Stream frames from the store.

xs cat <addr> [options]

Option	Description
<addr>	Address to connect to [HOST]:PORT or <PATH>
--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

Example:

xs cat ./store --follow

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
<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

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