Commands
cross.stream commands use Nushell
expressions to define reusable
operations that can be called on-demand with arguments. Unlike handlers which
maintain state between invocations, or generators which run continuously,
commands are stateless and execute independently each time they are called.
Defining Commands
To create a command, append a definition string with the topic
<command-name>.define
:
r#'{ process: {|frame| # frame.topic - always <command>.call # frame.hash - contains input content if present # frame.meta.args - contains call arguments let input = if ($frame.hash != null) { .cas $frame.hash } else { null } let n = $frame.meta.args.n 1..($n) | each {$"($in): ($input)"} }}'# | .append repeat.define
The command definition requires:
process
: A closure that receives the call frame and can return a pipeline of results
Each value in the closure’s output pipeline becomes a .recv
event
automatically.
Calling Commands
Commands are called by appending to <command-name>.call
with input content and
arguments:
# Call the repeat command with input and args"foo" | .append repeat.call --meta {args: {n: 3}}
Lifecycle Events
Commands emit events to track their execution:
Event | Description |
---|---|
<command>.recv | Output value from the command’s pipeline |
<command>.complete | Command execution finished successfully |
<command>.error | Error occurred during command execution |
All events include:
command_id
: ID of the command definitionframe_id
: ID of this specific invocation
Error Handling
If a command encounters an error during execution, it will:
- Emit a
<command>.error
frame with:- The error message
- Reference to both command_id and frame_id
- Stop processing the current invocation
Unlike generators, commands do not automatically restart on error - each invocation is independent.
Key Differences
Feature | Commands | Handlers | Generators |
---|---|---|---|
State | Stateless | Stateful between calls | Stateless |
Execution | On-demand | Event-driven | Continuous |
Results | Streamed immediately | Batched on completion | Streamed |
Parallelism | Multiple parallel calls | Sequential processing | Single instance |
Error Handling | Per-invocation | Unregisters handler | Auto-restarts |