xs.nu

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

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:

xs nu --install

Or use it directly in a session:

use xs.nu *

Stream Operations

.append

Append content to a topic. Wraps xs append.

.append <topic> [--meta <record>] [--ttl <ttl>] [--context <id>]

"My first note" | .append note
"Important note" | .append note --meta {priority: "high"}

.cat

Stream frames from the store. Wraps xs cat.

.cat [--follow] [--tail] [--topic <topic>] [--context <id>] [--all]

.cat --topic note
.cat -f --topic note  # Follow new notes

.head

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

.head <topic> [--follow] [--context <id>]

.head note
let latest_note = .head note

.remove

Remove a frame by ID. Wraps xs remove.

.remove <id>

let note_id = (.head note).id
.remove $note_id

.get

Retrieve a frame by ID. Wraps xs get.

.get <id>

let note_id = (.head note).id
.get $note_id

.exec

Execute a Nushell script with store helper commands available. Wraps xs exec.

.exec [<script>]

".cat --topic note | length" | .exec

SCRU128 ID Operations

.id

Generate a new SCRU128 ID. Wraps xs scru128.

.id

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

.id unpack

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

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

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

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

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

.cas <hash>

let note = .head note
.cas $note.hash  # Get the note content

Context Management

.ctx

Get the current context ID.

.ctx

.ctx-select

Interactively select a context from available contexts.

.ctx-select

.ctx-list

List all available contexts.

.ctx-list

Utilities

.cas-post

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

.cas-post

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

.import

Import frames from a backup directory. Wraps xs import.

.import <path>

.import ./notes-backup

.export

Export frames to a backup directory.

.export <path>

.export ./notes-backup

.tmp-spawn

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

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

The function:

• Creates a temporary directory with an xs store
• Starts xs serve in the background
• Sets $env.XS_ADDR and $env.XS_CONTEXT
• Runs your closure in this isolated environment
• Optionally starts an interactive Nushell session (with --interactive)
• Automatically cleans up the background process and temporary directory

.tmp-spawn {
  "test note" | .append note
  assert (.head 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 and $env.XS_CONTEXT
• 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 these environment variables when available:

• $env.XS_ADDR: Address to connect to (path or host:port)
• $env.XS_CONTEXT: Context ID for operations