comp:eq left=any right=any

True if left side is equal to right side

Output

bool

In expression mode, this method can be used via the the == operator.

This command accepts the following arguments:

• left the left side of the comparison.

• right the right side of the comparison.

Examples

eq 10 5
(10 == 5)

comp:gt left=any right=any

True if left side is greater than right side

Output

bool

In expression mode, this method can be used via the the > operator.

This command accepts the following arguments:

• left the left side of the comparison.

• right the right side of the comparison.

Examples

gt 10 5
(10 > 5)

comp:gte left=any right=any

True if left side is greater than or equal right side

Output

bool

In expression mode, this method can be used via the the >= operator.

This command accepts the following arguments:

• left the left side of the comparison.

• right the right side of the comparison.

Examples

gte 10 5
(10 >= 5)

comp:lt left=any right=any

True if left side is less than right side

Output

bool

In expression mode, this method can be used via the the < operator.

This command accepts the following arguments:

• left the left side of the comparison.

• right the right side of the comparison.

Examples

lt 10 5
(10 < 5)

comp:lte left=any right=any

True if left side is less than or equal than right side

Output

bool

In expression mode, this method can be used via the the <= operator.

This command accepts the following arguments:

• left the left side of the comparison.

• right the right side of the comparison.

Examples

lte 10 5
(10 <= 5)

comp:neq left=any right=any

True if left side is not equal to right side

Output

bool

In expression mode, this method can be used via the the != operator.

This command accepts the following arguments:

• left the left side of the comparison.

• right the right side of the comparison.

Examples

ne 10 5
(10 != 5)

comp:not argument=bool

Negates the argument

Output

bool

In expression mode, this method can be used via the the ! operator.

This command accepts the following arguments:

• argument the value to negate.

Examples

not $true
(!$true)

and condition:(bool|command)... -> boolean

True if all arguments are true

Every argument to and must be either a boolean or a command that returns a boolean. The and command will check all arguments in order, and if any of them are false, and will return false. If all conditions are true, and returns true.

Do note that and is a short circuiting command, meaning that if one of the conditions is found to be false, and will not evaluate any remaining closures.

In expression mode, this method can be used via the the and operator.

Examples

# true, if $file exists and is a symlink
and $($file:exists) {$(stat $file)[0]:is_symlink}

# true, if $file exists and is a symlink
($file.exists() and {stat($file)[0].is_symlink})

or condition:(bool|command)... -> boolean

True if any argument is true

Every argument to or must be either a boolean or a command that returns a boolean. The or command will check all arguments in order, and if any of them are true, or will return true. If all conditions are false, or returns false.

Do note that or is a short circuiting command, meaning that if one of the conditions is found to be true, or will not evaluate any remaining closures.

In expression mode, this method can be used via the the or operator.

Examples

$stat_out := $(stat $file)[0]

# true, if $file is either a symlink or a directory
or $stat_out:is_symlink $stat_out:is_dir

# true, if $file is either a symlink or a directory
($stat_out.is_symlink or $stat_out.is_dir)

control:assert condition=bool [message=string]

Error out if the condition is false.

Output

empty

This command accepts the following arguments:

• condition the condition to check.

• message (default: "Assertion failed") the message to show if the condition is false.

Examples

assert (1 + 1 == 2)
assert ($x > 0) "x must be positive"

control:bg job=integer

Resume a paused job, letting it continue running in the background.

Output

empty

Unlike a job started with a trailing & (which is in the background from the moment it starts), bg acts on a job that already exists and is currently paused (e.g. via crush:pause) -- it resumes it without putting it in the foreground the way fg would.

This command accepts the following arguments:

• job the job id of the paused job to resume in the background.

control:break

Break execution of a loop.

Output

empty

control:cmd command=file [<any>=any...] [arguments=any...]

Execute an external command

Output

binary_stream

Globs are file-expanded. Argument and switch order is preserved.

This command accepts the following arguments:

• command The file path to the command to execute

• <any>=$any Switches to pass in to the command. The name will be prepended with a double dash '--', unless it is a single character name, in which case a single dash '-' will be prepended

• arguments Arguments to pass in to the command

control:continue

Break execution of the current iteration of a loop and continue to the next lap.

Output

empty

control:fg [job=integer]

Return the output of a background pipeline

A job started with a trailing & runs in the background and registers its eventual result for later retrieval; fg waits for and returns that result.

This command accepts the following arguments:

• job the job id of the background job to put into the foreground.

Examples

# Create a pipe
$pipe := $($(table_input_stream value=$integer):pipe)
# Create a job that writes 100_000 integers to the pipe and put this job in the background
seq 100_000 | pipe:write &
# Create a second job that reads from the pipe and sums all the integers and put this job in the background
$sum_job_handle := $(pipe:read | sum &)
# Close the pipe so that the second job can finish
pipe:close
# Put the sum job in the foreground
fg $sum_job_handle

control:for [<any>=any...] body=command

Execute a command once for each element in a stream.

This command accepts the following arguments:

• <any>=$any the name to bind each element to, as name=stream (exactly one pair).

• body the block to execute once per element, with the bound name available as a variable.

Examples

# Iterate over the processes on the host
for i=$(host:procs) {
  echo $("Iterating over process {}":format $i:name)
}
# Print ten messages
for i=$(seq to=10) {
  echo $("Lap #{}":format $i)
}
# for is real grammar in expression mode too -- the loop variable is written
# with a $ sigil there (`for $i = ...`), not the bareword `name=stream` form
# command mode uses
assert (({
    $sum := 0
    for $i = $(seq 1 5) {
        $sum = ($sum + $i)
    }
    $sum
}()) == 10)

control:help [topic=any] [format=string]

Show help on the specified value.

Output

empty

The help command will show you help about a thing that you pass in. If you, for example pass in an integer (e.g. help 3), then you will see a help message about how crush represents integers and what methods an integer holds. You can also pass in any command to help (e.g. help $files for help on the files command). Note that you will need to prepend the $ sigil to the command name, since you're not using it as the command name.

If help's input is a pipeline, help shows help on the value in the pipeline. Otherwise, if a topic argument is given, help shows help on that value instead. With neither, help shows this introductory message.

This command accepts the following arguments:

• topic the topic you want help on.

• format (default: terminal, allowed: html, markdown, terminal) output format. The default, terminal, will render the help directly into the terminal. The other formats return a string containing either an html fragment or markdown.

Examples

# Show this message
help $help
# Show help on the root namespace
help $global

control:if condition=bool true_clause=command [else=string] [false_clause=command]

Conditionally execute a command once.

This command accepts the following arguments:

• condition the condition to filter on.

• true_clause the command to invoke if the condition is true.

• false_clause the (optional) command to invoke if the condition is false.

Examples

if ($a > 10) {
  echo big
} else {
  echo small
}
# if is real grammar in expression mode too, with the exact same syntax
assert ((if ($a > 10) { "big" } else { "small" }) == "big")

control:loop body=command

Repeatedly execute the body until the break command is called.

Output

empty

This command accepts the following arguments:

• body the command to repeatedly invoke.

Examples

loop {
  if $(i_am_tired) {
    break
  }
  echo Working
}
# loop is real grammar in expression mode too, with the exact same syntax
assert (({
    $i := 0
    $sum := 0
    loop {
        if ($i >= 5) { break }
        $sum = ($sum + $i)
        $i = ($i + 1)
    }
    $sum
}()) == 10)

control:match subject=any body=command

Branch on a value against a sequence of cases.

The body is a block containing a sequence of arms, where each arm is one of:

• case <value> {<body>} matches if the subject equals <value>.

• any <stream> {<body>} matches if the subject equals any individual value produced by reading <stream> (e.g. $(seq 5 10) or a list).

• is <type> {<body>} matches if the subject's type is <type>.

• default {<body>} always matches.

Arms are tried in order; the first one that matches runs, and the rest are skipped. If nothing matches, match errors.

This command accepts the following arguments:

• subject the value to match against.

• body a block containing the match's arms.

Examples

match $x {
    case 2 {echo "$x is 2"}
    any $(seq 5 10) {echo "$x is between 5 and 10"}
    is $string {echo "$x is a string"}
    default {echo "I don't know what $x is"}
}
# match is real grammar in expression mode too, with the exact same syntax
assert ((match $x {
    case 2 {"two"}
    any $(seq 5 10) {"between 5 and 10"}
    is $string {"a string"}
    default {"something else"}
}) == "two")

control:return [value=any]

break execution of a closure command and optionally return a value.

The return command can only be used when inside of a closure command. Closure blocks can not break early using the return command. Do note that you can use the return command inside of a closure block which is nested arbitrarily deeply inside of a closure command, which will stop execution of all inner blocks and return the closure command.

This command accepts the following arguments:

• value the value to return

Examples

# Define a factorial command
$factorial := {
  |$number: $integer|
  if ($number == 1) {
    return 1
  } else {
    return ($number * factorial($number - 1))
  }
}
# Call the command
factorial 5

control:schedule interval=duration [initial_delay=duration] [command=command] [--schedule_at_fixed_rate] [--once]

Schedule events at specified time intervals

• If a command is specified, timer will run the command at the specified cadence.

• If timer is used inside a pipeline, it will read one row of input at the specified cadence and write it out again.

• Otherwise, timer will simply write an empty row at the specified cadence.

If a command fails, the timer will stop.

This command accepts the following arguments:

• interval the interval between heartbeats.

• initial_delay the delay for the first heartbeat. If no initial delay is specified, use the interval parameter.

• command a command to run at each heartbeat.

• schedule_at_fixed_rate (default: false) if heart beat delivery starts blocking, catch up by sending more heartbeats afterwards.

• once (default: false) only schedule a single heartbeat. After that, exit.

Examples

# Show one row of the pipeline output every second
files / --recurse | schedule $(duration:of seconds=1)
# Wait for a second and then print hello once
schedule $(duration:of seconds=1) command={ echo hello } --once

control:sleep duration=duration

Pause execution of commands for the specified amount of time

This command accepts the following arguments:

• duration the time to sleep for.

Examples

sleep $(duration:of seconds=10)

control:source [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Evaluate files into current crush session

This command accepts the following arguments:

• files the files to source

Examples

source *.crush

control:throw error_type=string message=string

Raise a custom error, catchable and discriminable by its own error type.

Output

empty

Unlike every other error in Crush, a thrown error's type (as seen via catch {|$e| ...}'s $e:type) is error_type itself, not a fixed name tied to whatever went wrong internally -- so a script or library can define and catch its own error categories.

This command accepts the following arguments:

• error_type the error's type, e.g. "NotFound". Visible to a catch block as $e:type.

• message the error's message. Visible to a catch block as $e:message.

Examples

try { throw "NotFound" "no such user" } catch {|$e| assert ($e:type == "NotFound")}

control:timeit it=command [number=integer] [repeat=integer]

Execute a command many times and estimate the execution time.

This command accepts the following arguments:

• it the command to time.

• number the number of runs in each repeat. If unspecified, timeit will repeat enough times for each batch to take roughly 0.4 seconds.

• repeat (default: 5) repeat count. The average speed in the fastest repeat will be returned.

Examples

timeit {files|sort size}

control:timeout duration=duration command=command

Run a command, terminating it if it hasn't finished within the given duration.

If command finishes before duration elapses, timeout returns its result normally. Otherwise, a termination signal is sent to it -- the same cooperative mechanism crush:terminate uses, which only a command that actually checks for it (like sleep) will actually stop for; most builtins don't, and will keep running in the background regardless -- and timeout itself fails with a timeout error.

A command left running this way isn't just background noise: crush waits for every spawned thread to finish before the whole session exits, so a command that never cooperates and never finishes on its own (an infinite loop, for example) will keep the script -- or the whole interactive session -- from exiting cleanly, even though timeout itself already returned its error.

This command accepts the following arguments:

• duration how long to let the command run before terminating it.

• command the command to run.

Examples

timeout $(duration:of seconds=5) {sleep $(duration:of seconds=30)}

control:timer it=command

Execute a command once and return the execution time.

Output

duration

This command accepts the following arguments:

• it the command to time.

Examples

timer {files|sort size}

control:try body=command [catches=any...]

Execute a command, recovering from any error it produces.

If body fails, execution of body stops at the failing statement. Zero or more catch <filter>? {...} clauses may follow body, each the literal word catch, an optional filter (a string, glob, or regex -- anything implementing __is__, same as like/=~/match's is arm), and a block.

On failure, clauses are tried in order; the first one whose filter matches the error's type field (see below) -- or that has no filter at all -- runs, and the rest are skipped. Its block receives a struct describing the error as its single unnamed argument: message (the error text), type (the internal error variant's name, e.g. IOError, or a custom type set via throw), and command (the name of the command that failed, if known -- empty otherwise).

If no clause's filter matches, the error propagates normally, exactly as if try had no catch clauses of its own. With no catch clauses at all, an error is recovered from silently -- execution continues normally with whatever comes after try.

This command accepts the following arguments:

• body the command to attempt.

• catches zero or more catch <filter>? {...} clauses: the literal word catch, an optional filter pattern, and a block to run if that filter matches the error's type (or always, if no filter is given).

Examples

try {
  risky:command
} catch {
  |$error| echo ("Recovered: {}":format($error:message))
}
try {
  risky:command
} catch ^(Serde) {
  |$e| echo ("Serialization error: {}":format($e:message))
} catch Dns* {
  |$e| echo ("DNS error: {}":format($e:message))
}
# try/catch is real grammar in expression mode too, with the exact same syntax
# -- except a glob filter like Dns* above needs $(...) there, since glob literals
# only parse in command mode
assert ((try {
    throw("DnsTimeout", "no response")
} catch ^(Serde) {
    |$e| "serde"
} catch $(Dns*) {
    |$e| "dns"
}) == "dns")

control:which command=string

Find the path of an executable

Output

file

which searches the directories of the $crush:end[PATH] enivornment variable list for the specified command and returns the path to the first match.

This command accepts the following arguments:

• command the name of the command to find.

Examples

# Returns '/bin/ps'
which ps

control:while condition=command [body=command]

Repeatedly execute the body for as long the condition is met.

Output

empty

The loop body is optional. If not specified, the condition is executed until it returns false. This effectively means that the condition becomes the body, and the loop break check comes at the end of the loop.

This command accepts the following arguments:

• condition the condition.

• body the command to invoke as long as the condition is true.

Examples

while {./some_file:exists} {echo "hello"}
# while is real grammar in expression mode too -- the condition is a bare
# expression there, not wrapped in its own {...} block like in command mode
assert (({
    $i := 0
    $sum := 0
    while ($i < 5) {
        $sum = ($sum + $i)
        $i = ($i + 1)
    }
    $sum
}()) == 10)

crush:exit [status=integer] [--force]

Exit the shell

Output

empty

If other jobs are still running, exit fails with an error unless force is set, in which case those jobs are terminated first.

This command accepts the following arguments:

• status (default: 0) The exit status to set for the process

• force (default: false) Terminate all running jobs

crush:history

List previous commands

Output

table_input_stream idx=$integer command=$string

All previous invocation

crush:jobs

List running jobs

Output

table_input_stream id=$integer parent=$any description=$string type=$string status=$string

All currently running jobs

crush:language_mode

Returns the current language mode, either command or expression.

Output

string

Command mode is the default mode.

crush:pause jid=integer

Pause the given job.

Output

empty

This command accepts the following arguments:

• jid The job id for the job to pause

crush:resume jid=integer

Resume the given job.

Output

empty

This command accepts the following arguments:

• jid The job id for the job to resume

crush:run_mode

Returns how crush is currently running, either interactive or non-interactive.

Output

string

In interactive mode, the prompt is shown and commands are entered interactively with access to history, keyboard shortcuts, etc. In non-interactive mode, no prompt is shown and commands are read from a file. The run mode can not be changed while crush is running. It is decided by how crush was started.

crush:terminate jid=integer

Terminate the given job.

Output

empty

A job may continue running for some time after receiving a termination notification. Output pipelines produced by the job will still be readable and will contain any buffered IO already sent to the job before it received the termination notification.

This command accepts the following arguments:

• jid The job id for the job to terminate

Examples

# Create a job that produces a lot of output
$all_files := $(files --recurse /)
# Read a few lines of output
$all_files | head
# Find the job id of the job we want to terminate
crush:jobs
# Ask the job to terminate.
crush:terminate 1
# This will output the number of buffered rows that were buffered
$all_files | count

crush:threads

All the subthreads crush is currently running.

Output

table_input_stream job_id=$integer command_id=$integer created=$time name=$string

crush:byte_unit:get

Get the current byte unit.

Output

string

crush:byte_unit:list

List all available byte units.

Output

table_input_stream name=$string

crush:byte_unit:set byte_unit=string

Set the current byte unit.

Output

empty

This command accepts the following arguments:

• byte_unit the new byte unit.

crush:locale:get

Get the current locale.

Output

string

crush:locale:list

List all available locales.

Output

table_input_stream name=$string

crush:locale:set locale=string

Set the current locale.

Output

empty

This command accepts the following arguments:

• locale the new locale.

crush:prompt:get

Get the current prompt command.

crush:prompt:set [prompt=command]

Set a new prompt command.

Output

empty

This command accepts the following arguments:

• prompt The new command to invoke in order to produce a prompt

crush:title:get

Get the current title command

crush:title:set [title=command]

Set a new title command

Output

empty

This command accepts the following arguments:

• title The new command to invoke in order to produce a title

crush:warn:list

List recent warnings reported by commands that experienced a partial failure.

Output

table_input_stream timestamp=$time command=$string message=$string file=$string location=$string

Commands that continue past a partial failure (e.g. one bad row out of a stream) report it as a warning rather than aborting. A bounded number of the most recent warnings are kept here (see crush:warn:limit); in interactive mode, they are also printed as soon as they happen, unless disabled (see crush:warn:print).

crush:warn:new message=string

Report a warning to the bounded log crush:warn:list keeps.

Output

empty

Every builtin that presses on past a partial failure (each/where/group/files, and others) reports it through this exact same mechanism instead of aborting; this is that mechanism made directly callable, for a script or closure that wants to flag something without stopping.

This command accepts the following arguments:

• message the warning message to report.

Examples

crush:warn:new "something looked off, continuing anyway"

crush:warn:limit:get

Get how many warnings crush:warn:list keeps before evicting the oldest.

Output

integer

crush:warn:limit:set limit=integer

Set how many warnings crush:warn:list keeps before evicting the oldest.

Output

empty

This command accepts the following arguments:

• limit the new warning limit.

crush:warn:print:get

Get whether warnings are printed to the screen as they happen.

Output

bool

crush:warn:print:set print=bool

Set whether warnings are printed to the screen as they happen.

Output

empty

Only takes effect in interactive mode -- a warning is always recorded in crush:warn:list either way, this only controls whether it's also printed immediately. Defaults to true.

This command accepts the following arguments:

• print whether to print warnings to the screen as they happen.

Examples

crush:warn:print:set $false

dns:domain

DNS domain, if any

Output

any

Reads the local domain configured in /etc/resolv.conf's domain line, if any -- no network query is made. Returns $empty if none is configured.

dns:nameserver

List of default nameservers

Reads the nameservers configured in /etc/resolv.conf -- no network query is made. This is exactly what dns:query/dns:query_reverse themselves fall back to when their own nameserver argument is left unset (specifically, the first one listed).

dns:query name=string [record_type=string] [--tcp] [nameserver=string] [port=integer] [--no_follow_cname] [timeout=duration]

Look up a DNS record

The columns of the returned table depend on record_type:

• A, AAAA, NS, PTR, and CNAME: target (string) and ttl (duration)

• MX: target, preference (integer), and ttl

• SRV: target, priority, weight, port (all integer), and ttl

• TXT: text (binary) and ttl

• SOA: mname, rname (strings), serial (integer), and refresh, retry, expire, and ttl (all durations)

If a response's first answer is a CNAME record, it's followed transparently and the query is retried against the alias's target -- up to 8 hops, after which a chain that still hasn't resolved is a hard error rather than being followed forever (a spoofed or compromised nameserver could otherwise cause unbounded recursion, since plain UDP DNS has no cryptographic integrity). Set no_follow_cname=$true, or query for the CNAME record type directly, to see the alias itself instead of following it.

If nameserver isn't given, the first nameserver listed in /etc/resolv.conf is used (see dns:nameserver). name is always looked up exactly as given -- unlike most system resolvers, this does not consult /etc/resolv.conf's search domains (see dns:search_paths) to expand an unqualified name.

This command accepts the following arguments:

• name DNS record to look up.

• record_type (default: A, allowed: A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, TXT) DNS record type.

• tcp (default: false) use TCP as the transport instead of UDP.

• nameserver the nameserver to talk to. If none is given, use the nameservers configured in /etc/resolv.conf.

• port (default: 53) port to talk to the nameserver on.

• no_follow_cname (default: false) if a CNAME record is encountered, do not follow it. Show the actual CNAME record instead.

• timeout (default: 5s) connection timeout.

Examples

dns:query "www.google.com" AAAA
dns:query "example.com" MX
# See the alias itself instead of transparently following it
dns:query "www.example.com" CNAME

dns:query_reverse address=string [--tcp] [nameserver=string] [port=integer] [timeout=duration]

Perform a reverse DNS lookup on a given IP address

Looks up the hostname associated with address via a PTR record, automatically building the reverse-lookup name DNS uses for this (e.g. under in-addr.arpa for IPv4, ip6.arpa for IPv6) -- address should be given as a plain, forward IP address, not already reversed. Returns the hostname as a plain string, or nothing if no PTR record exists for that address. Unlike dns:query, this never follows a CNAME; a reverse zone is not expected to contain one.

This command accepts the following arguments:

• address IP address to look up. Can be either IPv4 or IPv6.

• tcp (default: false) Use TCP connection instead of UDP

• nameserver Override the nameserver to talk to

• port (default: 53) DNS port

• timeout (default: 5s) Connection timeout.

Examples

dns:query_reverse "127.0.0.1"

dns:search_paths

List of DNS search paths

Reads the DNS search domains configured in /etc/resolv.conf -- no network query is made. A system resolver normally appends these, in order, to an unqualified hostname before giving up (e.g. trying host.example.com when asked to resolve plain host); dns:query does not apply this itself -- name is always looked up exactly as given.

fs:cd destination=one_of $string $file $glob $re

Change to the specified working directory.

Output

empty

This command accepts the following arguments:

• destination the new working directory.

fs:cwd

Return the current working directory.

Output

file

fs:files [directory=one_of $string $file $glob $re...] [--recurse] [permissions=bool] [--inode] [links=bool] [user=bool] [group=bool] [size=bool] [--blocks] [modified=bool] [--accessed] [type=bool] [file=bool]

Show information about files and directories

If given no arguments, list the contents to the current working directory. If given any unnamed arguments, those will be the files and directories to list.

By default, files will not recurse into subdirectories. You can override this using the --recurse switch.

This command accepts the following arguments:

• directory directories and files to list

• recurse (default: false) recurse into subdirectories

• permissions (default: true) show permissions

• inode (default: false) show inode number

• links (default: true) show link count

• user (default: true) show username

• group (default: true) show group name

• size (default: true) show file size

• blocks (default: false) show block count

• modified (default: true) show modification time

• accessed (default: false) show time of last file access

• type (default: true) show file type

• file (default: true) show file name

fs:mounts

List filesystem mount points

Output

table_input_stream size=$integer available=$integer usage=$float format=$string readonly=$any name=$string path=$file

mounts outputs the following information about each mount point:

• size size in bytes.

• available available space in bytes.

• usage usage percentage.

• format filesystem type (ntfs, ext4, etc.).

• readonly whether the filesystem is mounted readonly.

• name name assigned to this mountpoint, if any.

• path the mount location.

fs:stat [destination=one_of $string $file $glob $re...] [--symlink]

Return a row with information about each file

Output

table_input_stream is_socket=$bool is_symlink=$bool is_file=$bool is_block=$bool is_dir=$bool is_char=$bool is_fifo=$bool inode=$integer nlink=$integer uid=$integer gid=$integer size=$integer block_size=$integer blocks=$integer access_time=$time modification_time=$time creation_time=$time file=$file

The return value contains the following columns:

• is_socket (bool) is the file is a socket

• is_symlink (bool) is the file a symbolic link

• is_block (bool) is the file a block device

• is_dir (bool) is the file is a directory

• is_char (bool) is the file a character_device

• is_fifo (bool) is the file a fifo

• inode (integer) the inode number of the file

• nlink (integer) the number of hardlinks to the file

• uid (integer) The user id of the file owner

• gid (integer) The group id of the file owner

• size (integer) File size in bytes

• block_size (integer) The size of a single block on the device storing this file

• blocks (integer) The number of blocks used to store this file

• access_time (time) The last time this file was accessed

• modification_time (time) The last time this file was modified

• creation_time (time) The time this file was created

• file (path) The filename

This command accepts the following arguments:

• destination the files to show the status for.

• symlink (default: false) stat symlinks, not the files they point to.

fs:usage [directory=one_of $string $file $glob $re...] [--silent] [--all]

Calculate the recursive directory space usage.

Output

table_input_stream size=$integer blocks=$integer file=$file

This command accepts the following arguments:

• directory the files to calculate the recursive size of.

• silent (default: false) do not show directory sizes for subdirectories.

• all (default: false) write sizes for all files, not just directories.

fs:watch path=one_of $string $file $glob $re [--recurse]

Watch a path for filesystem changes and stream them as rows.

Output

table_input_stream path=$file kind=$string timestamp=$time

Uses the operating system's native filesystem notification API (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows), so what counts as a change and how quickly it is reported is a best-effort property of the host OS, not a cross-platform guarantee -- rapid changes may be coalesced, and exact granularity differs by platform.

This command accepts the following arguments:

• path the path to watch.

• recurse (default: false) also watch subdirectories.

Examples

fs:watch . --recurse | where {kind == "Create(File)"}

grpc:connect host=string @ $(one_of $string $glob $re) [--plaintext] [timeout=duration] [port=integer]

Create a connection to a gRPC service.

gRPC (https://grpc.io) is Google's open-source, high-performance RPC framework, built on HTTP/2 and Protocol Buffers.

To send RPC calls to a server, you must first create a grpc connection, writing something like $conn := $(grpc:connect host=localhost service=* --plaintext).

The resulting connection struct will have one method for each endpoint on the chosen services of the host you connected to. When calling a method, there are two different ways to pass in input parameters.

If you want to pass exactly one message to the endpoint, e.g. because the endpoint does not use client streaming, you have the option of passing the fields of the message as arguments to the method call, e.g. $conn:ReverseString input=hello. The grpc methods support tab completion of argument names. They also come with help messages (e.g. help $conn:ReverseString) that describes the input and output format.

If you want to pass multiple messages to the endpoint, you must do so by piping in a table_input_stream, where the column names of the stream are identical to the field names of the message, e.g. list:of foo bar baz | select input={$value} | $conn:ReverseString

Output from a gRPC method call is always a $table_input_stream, with one row per message. If an endpoint does not use server side streaming, the output always has one row.

Once you are done with a gRPC connection, you should close it to free up resources. Do so by calling the close method, e.g. $conn:close.

This command accepts the following arguments:

• host the host to connect to.

• service the service to connect to on this host. This can be a string, a glob or a regular expression, in order to allow you to easily specify multiple services, e.g. use * to connect to all available services.

• plaintext (default: false) use plaintext instead of TLS to connect.

• timeout (default: 5s) the timeout for making calls.

• port (default: 50051) the port to connect to.

Examples

$conn := $(grpc:connect host=localhost service=* --plaintext)
# Returns "olleh"
$conn:ReverseString input="hello"
# Returns a stream with the values "oof", "rab", and "zab"
list:of foo bar baz | select input={$value} | $conn:ReverseString
# Close the connection once you're done
$conn:close

host:battery

List all batteries in the system and their status

Output

table_input_stream vendor=$string model=$string technology=$string cycle_count=$integer temperature=$float voltage=$float health=$float state=$string charge=$float time_to_full=$duration time_to_empty=$duration

host:memory

memory usage of this host.

Output

struct

The output struct contains the following fields:

• total, total amount of memory available to the host

• free, unused memory

• avail, available memory

• swap_total, total amount of swap available to the host

• swap_free, unused swap

host:name

name of this host

Output

string

host:procs

Return a table stream containing information on all running processes on this host

Output

table_input_stream pid=$integer ppid=$integer user=$string rss=$integer vms=$integer cpu=$duration name=$string

host:procs accepts no arguments.

host:signal [pid=integer...] [signal=string]

Send a signal to a set of processes

Output

empty

The set of existing signals is platform dependent, but common signals include SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGBUS, SIGFPE, SIGKILL, SIGUSR1, SIGSEGV, SIGUSR2, SIGPIPE, SIGALRM, SIGTERM, SIGCHLD, SIGCONT and SIGWINCH.

This command accepts the following arguments:

• pid the id of the process to send to.

• signal (default: SIGTERM) the name of the signal to send.

Examples

# Create a `killall` command that kills any process whose name matches the specified pattern
# The pattern can be a an exact string, a wildcard, or a regex
$killall := { |$victim| host:signal @$(host:procs|where {$name =~ $victim}|select pid | list:collect) signal=SIGKILL}
# Kill all crush commands
killall ^(crush)

host:threads

Return a table stream containing information on all running threads on this host

Output

table_input_stream tid=$integer pid=$integer priority=$integer user=$duration system=$duration name=$string

host:threads accepts no arguments.

host:uptime

uptime of this host

Output

duration

host:cpu:arch

the name of the CPU architecture

Output

string

host:cpu:count

number of CPU cores

Output

integer

host:cpu:load

current CPU load

Output

struct

host:os:name

name of the operating system

Output

string

host:os:version

version of the operating system kernel

Output

string

io:dir [value=any]

List the member names of a value.

Output

list $string

Works on any value -- a struct's own fields, a scope's local variables, or (for anything else, including a type value like $float) the methods its type declares.

If dir's input is a pipeline, dir lists the members of the value in the pipeline. Otherwise, dir requires a value to be provided as an argument, and lists the members of that value instead.

Pair with member to fetch one of the listed names -- member's own name argument, unlike the : operator, can be a runtime value instead of a fixed word in the source, so the two together let you enumerate and read members whose names aren't known ahead of time.

This command accepts the following arguments:

• value the value to list the members of.

Examples

dir .
# The full help text of every method float has
dir $float | each {|$name| help ($float | member $name)}

io:echo [values=any...] [--raw]

Prints all arguments directly to standard output.

Output

empty

If no arguments are passed to the values parameter, print the input pipeline value instead.

This command may at first appear pointless, since values entered on the prompt are printed to standard output by default. But that is only true when running a command interactively. When executing a file or running a closure, results are either completely ignored or returned as the return value of the block. In these situations, the echo command is useful for making sure a given value is written to standard output.

This command accepts the following arguments:

• values the values to print.

• raw (default: false) do not escape control characters in string values.

Examples

# These command invocations are equivalent
echo "Hello, world!"
"Hello, world!" | echo

io:http uri=string [method=string] [form=one_of $file $string $binary $binary_input_stream $glob $re] [header=string...] [timeout=duration]

Make a http request

Returns a struct with the following fields:

• status_code (integer) the http status code of the reply

• status_name (string) the name associated with the http status code

• header (list) the http headers of the reply

• body (binary_stream) the content of the reply

The http status codes and corresponding names are defined in https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

This command accepts the following arguments:

• uri URI to request

• method (default: GET, allowed: GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, PATCH, TRACE) the HTTP method to use in this request.

• form form content, if any.

• header HTTP headers, must be on the form "key:value".

• timeout (default: 5s) connection timeout.

Examples

http "https://example.com/" header=$("Authorization: Bearer {}":format $token)

io:member field=string [value=any]

Extract one named member from a value.

Works like the : member operator, except the member name is a runtime value (e.g. a variable) rather than a fixed word in the source -- use this when the name to look up isn't known until the script runs. Pair with dir to discover a value's member names first.

If member's input is a pipeline, member extracts the named member from the value in the pipeline. Otherwise, member requires a value to be provided as an argument, and extracts the named member from that value instead.

This command accepts the following arguments:

• field the member to extract.

• value the value to extract the member from.

Examples

$uri := "https://raw.githubusercontent.com/liljencrantz/crush/refs/heads/master/example_data/dinosaurs.json"
http $uri | member body | json:from
# member also takes its value as an argument instead of a pipe
member __neg__ 5
# dir lists a value's member names; member fetches one by name -- together
# they let you enumerate members whose names aren't known ahead of time
for name=$(dir 5) { echo (member $name 5) }

io:members

List the columns of any streamable input value as name/type pairs.

Output

table_input_stream name=$string type=$type

Works on anything that can be read as a stream of rows -- a table, a list, a dict, a struct, a scope -- and reports that stream's shape without consuming any of its actual rows.

Examples

$my_dict | members

io:readline [prompt=string] [history=string]

Read a string of input from the user.

Output

string

The readline command uses the same keyboard shortcuts as crush itself uses internally.

This command accepts the following arguments:

• prompt (default: "crush# ") the prompt to show the user.

• history load and save history under specified name.

Examples

# Ask the user for their name
echo "What is your name?"
$name := $(readline prompt="name: ")
echo $("Hello, {}!":format $name)

io:val value=any

Return value

Output

any

This command is useful if you want to pass a command as input in a pipeline instead of executing it. It is different from the echo command in that val sends the value through the pipeline, whereas echo prints it to screen.

This command accepts the following arguments:

• value the value to pass as output.

Examples

val $val

io:base64:from [files=one_of $file $string $binary $binary_input_stream $glob $re...] [alphabet=string]

Read a Base64 value and decode it.

Output

binary_stream

If no file is specified, use the input, which must be a binary or a string.

The standard alphabet follows RFC 4648, and uses a-z, A-Z, 0-9, +, and /. The urlsafe alphabet uses a-z, A-Z, 0-9, -, and .. Both use = for padding.

This command accepts the following arguments:

• files the files to read from. Read from input if no file is specified.

• alphabet (default: standard) base64 encoding style to use.

Examples

# Will output hello, world!
"aGVsbG8sIHdvcmxkIQ==" | base64:from

io:base64:to [file=one_of $string $file $glob $re] [alphabet=string]

Write specified binary or string as Base64

Output

binary_stream

If no file is specified, produce a binary stream as output.

The standard alphabet follows RFC 4648, and uses a-z, A-Z, 0-9, +, and /. The urlsafe alphabet uses a-z, A-Z, 0-9, -, and .. Both use = for padding.

This command accepts the following arguments:

• file the file to write to. Write to output if no file is specified.

• alphabet (default: standard) base64 encoding style to use.

Examples

# Will output aGVsbG8sIHdvcmxkIQ==
"hello, world!" | base64:to

io:bin:from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Read specified files (or input) as a binary stream

If no file is specified, the input must be either binary or a string which will be converted to a binary using utf-8.

This command accepts the following arguments:

• files source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

io:bin:to [file=one_of $string $file $glob $re]

Write specified iterator of strings to a file (or convert to BinaryStream) separated by newlines

This command accepts the following arguments:

• file destination file to write to. If unspecified, output is returned as a binary_stream.

io:csv:from [files=one_of $file $string $binary $binary_input_stream $glob $re...] [<any>=type...] [separator=string] [head=integer] [trim=string]

Parse specified files as CSV files

This command accepts the following arguments:

• files source. If unspecified, will read from input, which must be a binary or binary_stream.

• <any>=$type name and type of all columns.

• separator (default: ',') column separator.

• head (default: 0) skip this many lines of input from the beginning.

• trim trim this character from start and end of every value.

Examples

csv:from separator="," head=1 name=$string age=$integer nick=$string

io:hex:from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Read a hexadecimal value and decode it.

Output

binary_stream

If no file is specified, use the input, which must be a binary or a string.

This command accepts the following arguments:

• files the files to read from (read from input if no file is specified).

Examples

"68656c6c6f2c20776f726c6421" | hex:from

io:hex:to [file=one_of $string $file $glob $re]

Write specified binary or string as hexadecimal

Output

binary_stream

If no file is specified, produce a binary stream as output.

This command accepts the following arguments:

• file destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

"hello, world!" | hex:to

io:json:from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse json format

When deserializing a list, json:from will try to infer the type of the list. If all of the elements of the list are of the same type, the list will be parametrized to the same type. If all elements are objects, and all objects have the same set of fields with the same types, the list will be turned into a table.

This command accepts the following arguments:

• files source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

http "https://jsonplaceholder.typicode.com/todos/3"| member body | json:from

io:json:to [file=one_of $string $file $glob $re] [--compact]

Serialize to json format

When serializing a list, some types have to be squashed, because json does not have all the same types that Crush does:

• time values are turned into strings in the RFC 3339 format.

• duration values are turned into the integer number of seconds in the duration.

This command accepts the following arguments:

• file destination file to write to. If unspecified, output is returned as a binary_stream.

• compact (default: false) Disable line breaking and indentation.

Examples

files | json:to

io:lines:from [files=one_of $file $string $binary $binary_input_stream $glob $re...] [--skip_empty_lines] [--strip_whitespace]

Read specified files (or input) as a table with one line of text per row

Output

table_input_stream line=$string

This command accepts the following arguments:

• files the files to read from (read from input if no file is specified).

• skip_empty_lines (default: false) do not emit empty lines.

• strip_whitespace (default: false) strip whitespace from beginning and end of lines.

io:lines:to [file=one_of $string $file $glob $re]

Write specified stream of strings to a file (or convert to BinaryStream) separated by newlines

This command accepts the following arguments:

• file destination file to write to. If unspecified, output is returned as a binary_stream.

io:percent:from [input=string]

Decode a percent-encoded string.

Output

string

Replaces every %XX escape with the byte it represents. Errors if the decoded bytes aren't valid UTF-8.

This command accepts the following arguments:

• input the percent-encoded string to decode. Reads a string from input if unspecified.

Examples

# Returns "a b/c"
percent:from "a%20b%2Fc"

io:percent:to [input=string]

Percent-encode a string for safe use in a URL.

Output

string

Escapes every byte except the RFC 3986 unreserved set -- ASCII letters, digits, and -_.~ -- as %XX. This is the strictest common encoding, safe to use for a single path segment, query key, or query value. It does escape / and &, so don't apply it to an already-assembled path or query string, only to one component of one.

This command accepts the following arguments:

• input the string to percent-encode. Reads a string from input if unspecified.

Examples

# Returns "a%20b%2Fc"
percent:to "a b/c"

io:pup:from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse pup format

This command accepts the following arguments:

• files source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

pup:from serialized.pup

io:pup:to [file=one_of $string $file $glob $re]

Serialize to pup format

Pup is the native crush serialization format. All Crush types, including lambdas can be serialized to this format.

This command accepts the following arguments:

• file destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

files | pup:to

io:split:from [files=one_of $file $string $binary $binary_input_stream $glob $re...] separator=string [trim=string] [--allow_empty]

Read specified files (or input) as a table, split on the specified separator characters.

This command accepts the following arguments:

• files the files to read from (read from input if no file is specified).

• separator characters to split on

• trim characters to trim from start and end of each token.

• allow_empty (default: false) allow empty tokens.

io:toml:from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse toml format

Input can either be a binary stream or a file. All Toml types except datetime are supported. Datetime is not supported because the rust toml library currently doesn't support accessing the internal state of a datetime.

When deserializing a list, toml:from will try to infer the type of the list. If all of the elements of the list are of the same type, the list will be parametrized to the same type. If all elements are objects, and all objects have the same set of fields with the same types, the list will be turned into a table.

This command accepts the following arguments:

• files source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

toml:from Cargo.toml

io:toml:to [file=one_of $string $file $glob $re]

Serialize to toml format

If no file is specified, output is returned as a BinaryStream. The following Crush types are supported: File, string, integer, float, bool, list, table, table_input_stream, struct, time, duration, binary and binary_stream.

When serializing a list, some types have to be squashed, because toml does not have all the same types that Crush does:

• time values are turned into strings in the RFC 3339 format.

• duration values are turned into the integer number of seconds in the duration.

This command accepts the following arguments:

• file destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

$(files)[0] | toml:to

io:words:from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Read input and split on word boundaries.

Input can be files or the input pipe, which must be a binary input stream, split on word boundaries, trim away punctuation and discard empty "words".

This command accepts the following arguments:

• files the files to read from (read from input pipe if no file is specified).

io:yaml:from [files=one_of $file $string $binary $binary_input_stream $glob $re...]

Parse yaml format

When deserializing a list, yaml:from will try to infer the type of the list. If all of the elements of the list are of the same type, the list will be parametrized to the same type. If all elements are objects, and all objects have the same set of fields with the same types, the list will be turned into a table.

This command accepts the following arguments:

• files source to read from. If unspecified, will read from input, which must be a string, binary or binary_stream.

Examples

(http "https://jsonplaceholder.typicode.com/todos/3"):body | yaml:from

io:yaml:to [file=one_of $string $file $glob $re]

Serialize to yaml format

When serializing a list, some types have to be squashed, because yaml does not have all the same types that Crush does:

• time values are turned into strings in the RFC 3339 format.

• duration values are turned into the integer number of seconds in the duration.

This command accepts the following arguments:

• file destination file to write to. If unspecified, output is returned as a binary_stream.

Examples

files | yaml:to

math:abs number=$(one_of $float $integer)

The absolute value of number.

This command accepts the following arguments:

• number the number to take the absolute value of.

Examples

math:abs -5

math:acos number=$(one_of $float $integer)

The arc cosine of number.

Output

float

This command accepts the following arguments:

• number the value, between -1 and 1, to take the arc cosine of.

math:asin number=$(one_of $float $integer)

The arc sine of number.

Output

float

This command accepts the following arguments:

• number the value, between -1 and 1, to take the arc sine of.

math:atan number=$(one_of $float $integer)

The arc tangent of number.

Output

float

This command accepts the following arguments:

• number the value to take the arc tangent of.

math:ceil number=$(one_of $float $integer)

The smallest integer larger than number.

Output

float

This command accepts the following arguments:

• number the number to round up to the nearest integer.

math:clamp number=$(one_of $float $integer) min=$(one_of $float $integer) max=$(one_of $float $integer)

Number restricted to the inclusive range [min, max].

This command accepts the following arguments:

• number the number to clamp.

• min the lower bound of the allowed range.

• max the upper bound of the allowed range.

Examples

math:clamp 15 min=0 max=10

math:cos number=$(one_of $float $integer)

The cosine of number.

Output

float

This command accepts the following arguments:

• number the number to take the cosine of, in radians.

Examples

math:cos 1

math:exp number=$(one_of $float $integer)

e (Euler's number) raised to the power of number.

Output

float

The same result is available as math:pow math:e number, but exp doesn't require knowing about the e constant, and its dedicated implementation is generally more numerically precise than going through a general-purpose pow.

This command accepts the following arguments:

• number the exponent to raise e to.

Examples

# Returns 1, since e^0 is 1
math:exp 0

math:floor number=$(one_of $float $integer)

The largest integer smaller than number.

Output

float

This command accepts the following arguments:

• number the number to round down to the nearest integer.

math:ln number=$(one_of $float $integer)

The natural logarithm of number.

Output

float

This command accepts the following arguments:

• number the number to take the natural logarithm of.

math:log number=$(one_of $float $integer) base=$(one_of $float $integer)

The logarithm of number in base.

Output

float

This command accepts the following arguments:

• number the number to take the logarithm of.

• base the base of the logarithm.

math:pow base=$(one_of $float $integer) n=$(one_of $float $integer)

Raise the number to n.

Output

float

This command accepts the following arguments:

• base the base to raise to a power.

• n the exponent to raise the base to.

math:round number=$(one_of $float $integer)

Number rounded to the nearest whole number.

Output

float

This command accepts the following arguments:

• number the number to round to the nearest whole number.

math:sign number=$(one_of $float $integer)

-1, 0 or 1 depending on the sign of number.

This command accepts the following arguments:

• number the number to inspect the sign of.

Examples

math:sign -5

math:sin number=$(one_of $float $integer)

The sine of number.

Output

float

This command accepts the following arguments:

• number the number to take the sine of, in radians.

Examples

math:sin 1

math:sqrt number=$(one_of $float $integer)

The square root of number.

Output

float

This command accepts the following arguments:

• number the number to take the square root of.

math:tan number=$(one_of $float $integer)

The tangent of number.

Output

float

This command accepts the following arguments:

• number the number to take the tangent of, in radians.

random:float to=$(one_of $float $integer)

generate a random floating point number between 0 (inclusive) and 1 (exclusive)

Output

float

This command accepts the following arguments:

• to (default: 1.0) upper bound (exclusive).

random:float_stream to=$(one_of $float $integer)

generate a stream of random floating point numbers between 0 (inclusive) and 1 (exclusive)

Output

table_input_stream value=$float

This command accepts the following arguments:

• to (default: 1.0) upper bound (exclusive).

Examples

# Generate 20 floating point numbers between 0 and 100
random.float_stream 100 | head 20

random:integer [to=integer]

generate a random integer between 0 and 1 (or some other specified number)

Output

integer

This command accepts the following arguments:

• to (default: 2) upper bound (exclusive).

random:integer_stream [to=integer]

generate a stream of random integer numbers between 0 (inclusive) and 2 (exclusive)

Output

table_input_stream value=$integer

This command accepts the following arguments:

• to (default: 2) upper bound (exclusive).

Examples

# Generate 20 integers between 0 and 100
random.integer_stream 100 | head 20

remote:exec command=command host=string [username=string] [password=string] [host_file=one_of $string $file $glob $re] [--ignore_host_file] [--allow_not_found]

Execute a command on a remote host

Serializes command (a closure), sends it over SSH to host, runs it there in a fresh crush process, and returns its result. The remote host's key is checked against host_file unless ignore_host_file is set. Security note: setting ignore_host_file disables that check entirely (no protection against a different host answering at that address); allow_not_found instead trusts an unrecognized host's key on first use and saves it, rather than erroring -- both weaken protection against a machine-in-the-middle impersonating the remote host.

This command accepts the following arguments:

• command the command to execute.

• host host to execute the command on.

• username username on remote machines.

• password password on remote machines. If no password is provided, agent authentication will be used.

• host_file (~/.ssh/known_hosts) known hosts file.

• ignore_host_file (default: false) skip checking the know hosts file.

• allow_not_found (default: false) allow missing hosts in the known hosts file. Missing hosts will be automatically added to the file.

Examples

remote:exec {host:name} "my-server.example.com" username="alice"

remote:identity

List all known ssh-agent identities

Output

table_input_stream identity=$string public_key=$binary

remote:pexec command=command [host=string...] [parallel=integer] [username=string] [password=string] [host_file=one_of $string $file $glob $re] [--ignore_host_file] [--allow_not_found]

Execute a command on a set of hosts

Output

table_input_stream host=$string result=$any

Like exec, but runs command on every host listed in host (up to parallel of them at a time). pexec always attempts every host in the list, regardless of whether earlier hosts failed to connect or authenticate -- it never fails outright just because some, or even all, of the hosts couldn't be reached. A host that succeeds contributes one row (host/result columns) to the output; a host that fails contributes no row at all. Instead, the failure is logged as a warning (see crush:warn:list) naming the host and the underlying error. pexec's own exit status stays 0 either way, so the only way to tell whether every host succeeded is to compare the length of the output to the length of the host list you passed in -- fewer output rows than hosts means some connections failed. The same host-key verification applies independently to each host -- see exec for what ignore_host_file/allow_not_found mean for security.

This command accepts the following arguments:

• command the command to execute.

• host hosts to execute the command on.

• parallel (default: 32) maximum number of hosts to run on in parallel.

• username username on remote machines.

• password password on remote machines. If no password is provided, agent authentication will be used.

• host_file (~/.ssh/known_hosts) known hosts file.

• ignore_host_file (default: false) skip checking the know hosts file.

• allow_not_found (default: false) allow missing hosts in the known hosts file. Missing hosts will be automatically added to the file.

Examples

remote:pexec {host:name} "web1.example.com" "web2.example.com" username="alice"

remote:host:list [host_file=one_of $string $file $glob $re]

List all known hosts

Output

table_input_stream host=$string public_key=$string

If a given host key has no hostname, the hostname will be the empty string

This command accepts the following arguments:

• host_file (~/.ssh/known_hosts) known hosts file.

remote:host:remove [host_file=one_of $string $file $glob $re] @ $(one_of $string $glob $re) @ $(one_of $string $glob $re)

Remove hosts from known_hosts file

Output

integer

Remove all hosts that match both the host and the key filters. Returns the number of host entries deleted.

This command accepts the following arguments:

• host_file (~/.ssh/known_hosts) known hosts file.

• host host filter.

• key key filter.

sockets:tcp

List open TCP sockets

Output

table_input_stream local_address=$string local_port=$integer remote_address=$string remote_port=$integer pids=$(list $integer) state=$string

sockets:udp

List open UDP sockets

Output

table_input_stream local_address=$string local_port=$integer pids=$(list $integer)

stream:all_match condition=command

True if condition is true for every row of input.

Output

bool

Stops reading input as soon as one non-matching row is found, rather than always consuming the whole stream. True for an empty input, same as an empty and chain would be. The columns of the row are exported to condition by name, exactly like where.

This command accepts the following arguments:

• condition the condition to check for each row.

Examples

# Are all processes owned by root?
host:procs | all_match {($user == "root")}

stream:any_match condition=command

True if condition is true for at least one row of input.

Output

bool

Stops reading input as soon as one matching row is found, rather than always consuming the whole stream. The columns of the row are exported to condition by name, exactly like where.

This command accepts the following arguments:

• condition the condition to check for each row.

Examples

# Is there any process using more than 50% of a CPU core?
host:procs | any_match {($cpu > 50)}

stream:avg [field=string]

Calculate the average for the specific column across all rows.

If the input only has one column, the column name is optional. The column type must be numeric or a duration.

This command accepts the following arguments:

• field The name of the column to find the average of

Examples

host:procs | avg cpu

stream:concat [field=string] [separator=string]

Concatenate all values of the specified column across all rows

If the input only has one column, the column name is optional. The column can be numeric, or textual.

This command accepts the following arguments:

• field The name of the column to concatenate

• separator (default: ", ") The separator to insert between each element

Examples

host:procs | concat name ":"

stream:count

Count the number of rows in the input.

Output

integer

The input type can be any type that can be streamed, such as a table, a list, etc. If the input type is not a materialized type, such as a $table_input_stream, the whole stream will be consumed by this operation. Materialized types, i.e. $table, $list and $dict, have a know size, and count will not need to iterate over them to find it.

Examples

# Returns the number of processes on the system
host:procs | count

stream:drop [drop=string...]

Drop specified columns from input stream, copy content of remaining columns into output

This command is does the opposite of the select command. It copies all columns except the ones specified from input to output.

This command accepts the following arguments:

• drop the columns to remove from the stream.

Examples

# Drop memory usage columns from output of ps
host:procs | drop vms rss

stream:each body=command

Runs a command one for each row of input

Output

empty

The columns of the row are exported to the environment using the column names.

This command accepts the following arguments:

• body the command to run.

Examples

host:procs | where {$status != "Sleeping"} | each {echo ("{} is sleepy":format $name)}

stream:fold initial=any body=command

Accumulate a single result across all rows of input using a user-supplied closure.

body is called once per input row, with the accumulator available as acc and the row's own columns exported by name, exactly like where/each. Its return value becomes the accumulator for the next row; once the input is exhausted, the final accumulator is fold's own output. This is the general escape hatch for one-off aggregations that don't have (or don't need) their own dedicated command like sum or max.

This command accepts the following arguments:

• initial the accumulator's value before the first row is processed.

• body called once per row with the accumulator (acc) and the row's own columns as named arguments; its return value is the next accumulator.

Examples

# Sum 1 through 5 by hand
seq 1 6 | fold {($acc + $value)} initial=0
# Build a comma separated string from a column
files | fold {("{}, {}":format($acc, $file))} initial=""

stream:group [group_by=string...] [<any>=command...]

Group stream by the specified column(s)

This command accepts the following arguments:

• group_by the column(s) to group by and copy into the output stream.

• <any>=$command create additional columns by aggregating the grouped rows using the supplied aggregation command. The supplied command will be called once for each group, with a table_input_stream containing all rows within that group. Whatever the command outputs will be the value for the specified column for that group.

Examples

# Group files in current tree by the number of hardlinks pointing to them, show
# the number of files and the sum total file size for each link count. Sort results
# by size.
files --recurse | group links file_count=$count size={sum size} | sort size

stream:head [rows=integer]

Return the first row(s) of the input.

Output

A stream with the same columns as the input

This command accepts the following arguments:

• rows (default: 10) the number of rows to return.

stream:join [<any>=any...]

Join two streams together on the specified keys.

This command accepts the following arguments:

• <any>=$any Fields to join

Examples

join user=$(files) name=$(users:list)

stream:max [field=string]

Calculate the maximum for the specific column across all rows.

If the input only has one column, the column name is optional. The column can be numeric, temporal, a string or a file.

This command accepts the following arguments:

• field The name of the column to find the maximum of

Examples

host:procs | max cpu

stream:median [field=string]

Calculate the median for the specific column across all rows.

If the input only has one column, the column name is optional. The column type must be numeric or a duration. If the column contains a NaN float value, median fails with an error rather than silently including it in (or excluding it from) the calculation.

This command accepts the following arguments:

• field The name of the column to find the median of

Examples

host:procs | median cpu

stream:min [field=string]

Calculate the minimum for the specific column across all rows.

If the input only has one column, the column name is optional. The column can be numeric, temporal, a string or a file.

This command accepts the following arguments:

• field The name of the column to find the minimum of

Examples

host:procs | min cpu

stream:prod [field=string]

Calculate the product of the specified column across all rows.

Specifying the column is optional if the stream only has one column. The column type must be numeric.

This command accepts the following arguments:

• field The name of the column to find the product of

Examples

seq 5 10 | prod

stream:rename [<any>=string...]

Rename one or more columns of a stream.

Output

A stream with the same columns as the input

Every argument name is the current name of a column, and its value is the new name to give it. Columns not mentioned pass through unchanged.

This command accepts the following arguments:

• <any>=$string mapping from current column name to new column name.

Examples

files | rename file=path

stream:reverse

Reverses the order of the rows in the input

Output

A stream with the same columns as the input

stream:sample [rows=integer]

Reservoir-sample rows rows from the input.

Output

A stream with the same columns as the input

Every row of input has an equal probability of ending up in the output, and the whole stream never has to be materialized to pick them -- only rows rows are ever held in memory at once. Output order is not the input order.

This command accepts the following arguments:

• rows (default: 10) the number of rows to sample.

Examples

# Pick 5 pseudo-random lines out of a huge file, without reading it all into memory
lines:from big_log_file.txt | sample 5

stream:select [copy_fields:string...] [*] [new_field=command]

Pass on some old fields and calculate new ones for each line of input

Examples

# Show only the filename and discard all other columns
files | select file

# Add an extra column to the output of files that shows the time passed since last modification
files | select * age={(time.now() - modified)}

stream:seq [args=integer...] [from=integer] [to=integer] [step=integer]

Return a stream of sequential numbers

With no arguments, seq counts forever starting at 0. Given one to three unnamed numbers, they're interpreted the same way Python's range does: seq to counts from 0 up to (but not including) to; seq from to starts at from instead; seq from to step also sets the step size. The from, to, and step named arguments below are equivalent to the two- and three-number unnamed forms, spelled out -- but can't be mixed with the unnamed form in the same call, since e.g. seq 3 to=10 would leave it ambiguous which one actually sets the end of the sequence.

This command accepts the following arguments:

• args 1 to 3 numbers: to, from to, or from to step -- see the command's own long help. Can't be combined with the from/to/step named arguments.

• from the first number in the sequence. Defaults to 0.

• to the end of the sequence (exclusive). If not specified, the sequence will continue forever.

• step the step size. Defaults to 1.

Examples

seq 3
# Prepend an index column to the output of the files command
zip $(seq) $(files)

stream:skip [rows=integer]

Skip the specified number of rows from the beginning of the stream and return the remainder.

Output

A stream with the same columns as the input

If the stream has fewer than the specified number of rows, an empty stream will be returned.

This command accepts the following arguments:

• rows (default: 1) the number of rows to skip.

stream:sort [field=string...] [--reverse] [--case_insensitive]

Sort input stream based on one or more of it's columns

Output

A stream with the same columns as the input

If any sort column contains a NaN float value, sort fails with an error rather than picking an arbitrary position for it, since NaN has no defined ordering relative to other floats.

This command accepts the following arguments:

• field the columns to sort on. Optional if input only has one column.

• reverse (default: false) reverse the sort order.

• case_insensitive (default: false) ignore case when sorting textual columns.

Examples

# Show the contents of the current directory, sorted first on type and then on filename
files | sort type file

stream:sum [field=string]

Calculate the sum for the specific column across all rows.

If the input only has one column, the column name is optional.

The column contents must be exactly one of the types $integer, $float, or $duration.

Normally, sum expects the type of the column to be the type to sum over, but sum can also sum over a column of type any, so long as there is at least one row in the table, and all the rows are actually of the same type.

This command accepts the following arguments:

• field The name of the column to find the sum of

Examples

host:procs | sum cpu

stream:tail [rows=integer]

Return the last row(s) of the input.

Output

A stream with the same columns as the input

This command accepts the following arguments:

• rows (default: 10) the number of rows to return.

stream:tee [branches=command...]

Duplicate the input stream into one or more side pipelines, passing the original stream through unchanged.

Output

A stream with the same columns as the input

Each branches block receives its own independent copy of every row and runs to completion as its own pipeline, in parallel with the others; its own output is discarded, so a branch is only useful for its side effects (writing to a file, counting, etc). tee's own output is the untouched original stream, so it composes directly into a larger pipeline. If a branch fails, the failure is reported via crush:warn:list rather than aborting tee or the other branches.

This command accepts the following arguments:

• branches one or more pipelines to send an independent copy of the stream through.

Examples

# Write a snapshot to disk while continuing to filter the live stream
host:procs | tee {json:to snapshot.json} | where {($cpu > 50)}

stream:union [streams=any...]

Concatenate two or more streams with identical column types into one.

Every row of the first stream is output, in order, followed by every row of the second stream, and so on. All streams must have identical column types.

This command accepts the following arguments:

• streams the streams to concatenate.

Examples

union $(seq 0 3) $(seq 10 13)

stream:uniq [field=string]

Only output the first row whenever multiple rows has the same value for the specified column

Output

A stream with the same columns as the input

If no column is given, the entire rows are compared.

This command does not just remove consecutive repeated column values, any repeated column values over the entire stream are removed.

This command accepts the following arguments:

• field The field to compare.

Examples

host:procs | uniq user

stream:where condition=command

Filter out rows from input based on condition

Output

A stream with the same columns as the input

The columns of the row are exported to the environment using the column names, i.e. if the table the where command is applied to has columns a and b, then the environment will have variables type and name, the variables $type and $name will be set to the values of the columns in the current row on each execution of the closure.

This command accepts the following arguments:

• condition the condition to filter on.

Examples

# List all subdirectories to the current working directory
files | where {$type == directory}

stream:zip first=any second=any

Combine two streams of data into one containing one row of each input stream in each row of output.

If the two streams have different numbers of rows, the longer stream will be truncated to the length of the shorter one.

This command accepts the following arguments:

• first the first stream.

• second the second stream.

Examples

# Prepend an index column to the output of the files command
zip $(seq) $(files)

types:class [parent=struct]

Create an empty new class

Output

struct

This command accepts the following arguments:

• parent the parent type to inherit members from (if any).

Examples

# Create a class that represents a point in 2D space
$Point := $(class)
$Point:__short_help__ = "A point in 2D space"
$Point:__signature__ = "class Point"
$Point:__long_help__ = "Uses floating point numbers to represent the x and y coordinates"
$Point:__example__ = "$p := ($Point.new(1.0, 2.0))"
# Constructor takes two arguments, x and y
Point:__init__ = {
  |$x:$float $y:$float|
  $this:x = $x
  $this:y = $y
}

Point:len = {
  |
  short_help = "Returns the distance from the origin"
  |
  ($math.sqrt($this.x*$this.x + $this.y*$this.y))
}
# Overload the `+` operator to add two points. (Only available in expression mode)
Point:__add__ = {
  |
  short_help = "Add two points together"
  $other : $struct "the other point."
  |
  ($Point.new(x=($this.x+$other.x), y=($this.y+$other.y)))
}
$p := $($Point:new x=1.0 y=2.0)
$p:len
$p2 := ($Point.new(x=-1.0, y=2.0))
$p3 := ($p + $p2)

types:convert target_type=type [value=any]

Convert the value to the specified type

Converting a value to the type it already holds always works and returns the original value. Most other conversions take the input value, convert it to a string and then attempt to parse that string as the desired type.

The following short cut conversions exist that do not go via a string representation:

• $float to $integer the value is truncated to its integer part.

• $integer to $bool 0 is false, all other values are true.

If convert's input is a pipeline, convert converts the value in the pipeline. Otherwise, convert requires a value to be provided as an argument, and converts that value instead.

This command accepts the following arguments:

• target_type the type to convert the value to.

• value the value to convert.

Examples

convert $integer 1.8

types:definition command=command

Returns the definition of the specified closure as a text string

Output

string

Returns nothing if the command is not a closure

Note that the outputted of the definition builtin is reformatted, including switching code between expression mode and command mode.

This command accepts the following arguments:

• command the closure to show the definition of.

Examples

# returns { $files --recursive '/'}
$all_the_files := {files --recursive /}
definition $all_the_files