Skip to content
cross.stream

xs.nu

The xs.nu module provides Nushell-friendly wrappers around the core xs CLI commands, enabling seamless pipeline integration and environment-aware operations. See for naming rules and wildcards.

All functions automatically use the $env.XS_ADDR environment variable when connecting to stores, supporting local paths, TCP addresses, and iroh peer-to-peer QUIC connections. See Exposing Streams reference for connection setup and remote access configuration.

Installation

Install the module into your Nushell configuration:

Terminal window
xs nu --install

Or use it directly in a session:

Terminal window
use xs.nu *

Stream Operations

.append

Append content to a topic. Wraps xs append.

Terminal window
.append <topic> [--meta <record>] [--ttl <ttl>]
Terminal window
"My first note" | .append note
"Important note" | .append note --meta {priority: "high"}

.cat

Stream frames from the store. Wraps xs cat.

Terminal window
.cat [--follow] [--new] [--after <id>] [--from <id>] [--last <n>] [--topic <topic>]
Terminal window
.cat --topic note
.cat -f --topic note  # Follow new notes
.cat --last 10        # Show last 10 events

.last

Get the most recent frame for a topic. Wraps xs last.

Terminal window
.last <topic> [--follow]
Terminal window
.last note
let latest_note = .last note

.remove

Remove a frame by ID. Wraps xs remove.

Terminal window
.remove <id>
Terminal window
let note_id = (.last note).id
.remove $note_id

.get

Retrieve a frame by ID. Wraps xs get.

Terminal window
.get <id>
Terminal window
let note_id = (.last note).id
.get $note_id

.eval

Evaluate a Nushell script with store helper commands available. Wraps xs eval.

Terminal window
.eval [<script>]
Terminal window
".cat --topic note | length" | .eval

SCRU128 ID Operations

.id

Generate a new SCRU128 ID. Wraps xs scru128.

Terminal window
.id
Terminal window
let new_id = .id
# => "03d4q1qhbiv09ovtuhokw5yxv"

.id unpack

Unpack a SCRU128 ID into its component fields. Wraps xs scru128 unpack.

Terminal window
.id unpack [<id>]

The function accepts the ID as an argument or via pipeline input. The timestamp is converted to a native Nushell datetime type.

Terminal window
# Using argument
.id unpack "03d4q1qhbiv09ovtuhokw5yxv"


# Using pipeline
"03d4q1qhbiv09ovtuhokw5yxv" | .id unpack


# Using with generated ID
.id | .id unpack
# =>
# ╭────────────┬──────────╮
# │ timestamp  │ now      │
# │ counter_hi │ 1234     │
# │ counter_lo │ 5678     │
# │ node       │ abcd1234 │
# ╰────────────┴──────────╯

.id pack

Pack component fields into a SCRU128 ID. Wraps xs scru128 pack.

Terminal window
.id pack [<components>]

The function accepts a record as an argument or via pipeline input. Nushell datetime values are automatically converted to the required float timestamp format.

Terminal window
# Using argument
let components = {
  timestamp: (date now)
  counter_hi: 1234
  counter_lo: 5678
  node: "abcd1234"
}
.id pack $components


# Using pipeline (round-trip example)
.id | .id unpack | .id pack

The SCRU128 functions provide perfect round-trip compatibility while leveraging Nushell’s native data types for timestamps.

Content Storage

.cas

Retrieve content from Content-Addressable Storage by hash. Wraps xs cas.

Terminal window
.cas <hash>
Terminal window
let note = .last note
.cas $note.hash  # Get the note content

Utilities

.cas-post

Store content in Content-Addressable Storage. Wraps xs cas-post.

Terminal window
.cas-post
Terminal window
"note content" | .cas-post  # Returns content hash

.import

Import frames from a backup directory. Wraps xs import.

Terminal window
.import <path>
Terminal window
.import ./notes-backup

.export

Export frames to a backup directory.

Terminal window
.export <path>
Terminal window
.export ./notes-backup

.tmp-spawn

Spawn a temporary xs serve instance, run a closure, then cleanup. Useful for testing and isolated operations.

Terminal window
.tmp-spawn <closure> [--interactive]

The function:

  • Creates a temporary directory with an xs store
  • Starts xs serve in the background
  • Sets $env.XS_ADDR
  • Runs your closure in this isolated environment
  • Optionally starts an interactive Nushell session (with --interactive)
  • Automatically cleans up the background process and temporary directory
Terminal window
.tmp-spawn {
  "test note" | .append note
  assert (.last note).hash != null
  print "Test passed!"
}


# Start an interactive session after running the closure
.tmp-spawn --interactive {
  "setup note" | .append note
  print "Setup complete - dropping to interactive shell"
}

This is particularly useful for integration tests where you need a clean, isolated cross.stream environment. The --interactive flag is especially helpful for debugging and exploration, as it allows you to interact with the temporary environment after your setup code runs.

Key Advantages

The xs.nu functions provide several advantages over direct CLI usage:

  • Pipeline Integration: All functions work naturally in Nushell pipelines
  • Environment Awareness: Automatic detection of $env.XS_ADDR
  • Type Safety: Return structured Nushell records instead of raw JSON strings
  • Native Data Types: SCRU128 timestamps use native Nushell datetime types
  • Error Handling: Proper Nushell error propagation
  • Convenience: Simplified parameter handling and defaults

Environment Variables

Many functions automatically use this environment variable when available:

  • $env.XS_ADDR: Address to connect to (path or host:port)