Command Reference

Change working directory. Supports ~, -, .., and absolute or relative paths.

Auto-cd: type a directory name directly to change into it without the cd command.

Push the current directory onto the stack and change to the given directory.

Pop the top directory from the stack and cd into it.

Display the current directory stack. Entries are in pushd order.

Print the absolute path of the current working directory.

List directory contents as a structured table with name, type, size, and modified columns.

Smart jump to a directory using frecency-based fuzzy matching. Learns from your cd history.

Interactive fuzzy directory picker powered by fzf-style UI. Shows all visited directories.

Set or list environment variables. Without arguments, prints all exported variables.

Remove a shell variable or function from the current environment.

Mark a variable as read-only. Any subsequent assignment will fail.

Declare a constant (immutable) variable. Cannot be reassigned after creation.

Execute a block with scoped environment variables. Variables revert after block ends.

Declare a variable scoped to the current function. Not visible outside the function.

Declare variables with type attributes. Supports arrays, associative arrays, exports, and dedup.

Set variable attributes (zsh-compatible). Often used with -U for deduplication.

Set shell runtime options. Controls error handling, tracing, and safety behaviors.

Display or set the file creation permission mask. Affects permissions of newly created files.

Get or set resource limits for the current shell process (file size, open files, memory, etc).

Create, list, or remove command aliases. Supports suffix aliases with -s.

Remove one or all aliases from the current session.

Launch the interactive configuration wizard. Shorthand for 'config wizard'.

Manage shell configuration. Subcommands include wizard, show, reset, edit, save, and set.

Apply a built-in color theme to the shell prompt and UI.

Print arguments to stdout. Supports escape sequences with -e and raw mode with -E.

Format and print data using C-style format specifiers (%s, %d, %f, %x).

zsh-style print with options for per-line output, raw mode, and prompt expansion.

Read a line of input from stdin into a variable.

Execute commands from a file in the current shell context. Variables and functions persist.

Execute commands from a file in the current shell (alias for source).

Evaluate a string as a shell command. Useful for dynamically constructed commands.

Replace the current shell process with the given command. Does not return.

Evaluate a conditional expression. Returns exit code 0 (true) or 1 (false).

Evaluate a conditional expression (alias for test). Must end with ].

Show how a command name is interpreted (alias, function, builtin, or external).

Execute a command string or block. Useful for inline command evaluation.

Silently discard all output from the pipeline. Useful for suppressing noisy commands.

Prompt the user for interactive text input and return the entered string.

Present an interactive menu of items and return the user's selection.

Import a module or file into the current scope. Brings exported commands and variables.

View command history or clear it. Shows numbered entries with timestamps.

List or re-edit recent history commands. Opens in $EDITOR for editing before re-execution.

History expansion shortcuts. !! repeats last command, !n repeats command N, ^old^new substitutes.

List all active background jobs with their status, PID, and command.

Bring a background job to the foreground. Resumes a stopped job.

Continue a stopped job in the background.

Wait for one or all background jobs to complete before continuing.

Remove a job from the job table so it is not killed when the shell exits.

Send a signal to a process or job. Default signal is SIGTERM (15).

Set or display signal handlers. Run a command when a specific signal is received.

Schedule a command for future execution after a delay or at a specific time.

Suspend the current shell process (send SIGTSTP to self).

Conditional execution with if/elif/else branches. Executes the block whose condition is true.

Iterate over a list of values, executing the body block for each item.

Loop while a condition is true. Also supports until (loop until true).

Pattern matching on a value. Each branch is a glob pattern followed by commands.

Modern pattern matching expression. More powerful than case with structured pattern support.

Error handling with try/catch/finally blocks. Catch block receives the error.

Define a custom command with named and typed parameters.

Present a numbered menu of items for the user to choose from.

Extended conditional test with pattern matching and logical operators. More powerful than [.

Return from the current function with an optional exit status code.

Exit from the innermost loop (for, while, until). Optional N exits N levels.

Skip the rest of the current loop iteration and jump to the next one.

Parse positional parameters according to an option string. Used in scripts for argument handling.

Shift positional parameters left by N positions (default: 1). $2 becomes $1, etc.

Manage the shell's command hash table. Speeds up command lookups by caching paths.

Print accumulated CPU times for the shell and all child processes.

Measure the wall-clock and CPU execution time of a command.

Return exit code 0 (success). Useful as a no-op condition in loops.

Return exit code 1 (failure). Useful for testing error paths.

No-op command that returns success (exit 0). Used as a placeholder in scripts.

List or set custom keybindings for the line editor. Bind key sequences to widgets.

Run a command bypassing shell functions and aliases. With -v, show command location.

Run a shell builtin command explicitly, bypassing any functions or aliases with the same name.

Mark a function for lazy-loading from $fpath. Function is loaded on first call.

Execute a command N times in sequence.

Locate a command and show its full path, or indicate if it is a builtin/alias/function.

Locate a command (zsh-compatible alias for which). Shows how a name resolves.

Tamper-evident audit logging with SHA-256 hash chain. Records all command executions.

Command execution policy engine. Allow, deny, or require confirmation for specific commands.

System information dashboard showing host, CPU, memory, disk, network, and battery.

Interactive wizard to cleanly uninstall zy shell, removing configs and restoring default shell.

Exit the shell with an optional exit code. Running jobs are warned about.

Show general help or detailed per-command help with syntax, examples, and flags.

Toggle runtime feature gates on or off. Controls experimental or optional behaviors.

Register shell lifecycle hooks that run on events like precmd, preexec, chpwd, and exit.

Built-in HTTP client supporting GET, POST, HEAD, PUT, DELETE methods.

Plugin management system. List, enable, disable, and reload shell plugins.

Execute and manage shell skills (reusable task automation scripts).

Show command usage statistics including most-used commands, session time, and command counts.

Clear the terminal screen and move cursor to the top-left.

Check if the current shell is running with root/administrator privileges.

Find and return a free TCP port number on the local machine.

List all running processes as a structured table with PID, name, CPU, and memory.

Pause execution for a specified duration. Supports units like sec, ms, min.

Get the terminal dimensions (columns and rows) as a record.

Display system and kernel information (OS name, version, architecture).

Decode a percent-encoded URL string back to its original form.

Percent-encode a string for safe use in URLs.

Parse a URL into its components (scheme, host, port, path, query, fragment).

Show the zy shell version, build date, commit hash, and feature flags.

Print the current username.

Set a zsh-style shell option. Silently accepted for compatibility with .zshrc files.

Unset a zsh-style shell option.

Emulate another shell's behavior mode. Used for zsh/sh/ksh compatibility layers.

Load or unload zsh modules. Stub for compatibility — silently succeeds.

Configure completion and other style settings. Zsh-compatible stub.

Initialize the completion system. Zsh-compatible stub — zy auto-initializes completions.

Associate a completion function with one or more commands.

Access and manipulate the Zsh Line Editor widgets. Stub for widget compatibility.

Format a Unix timestamp or the current time using strftime format specifiers.

Display detailed file status information (size, permissions, timestamps).

Match a string against a Perl-compatible regular expression.

Parse command-line options from an argument array into associative arrays.

Built-in FTP client. Zsh-compatible stub for basic FTP operations.

Open, listen, or close raw TCP socket connections.

Start and manage commands in pseudo-terminal sessions.

Monitor user login and logout events on the system.

Add completion candidates to the current completion reply array.

Generate completion matches. Bash-compatible interface for generating word lists.

Parse and define argument/option completion specs for a command (zsh-style).

Register a completion function for a command. Bash-compatible interface.

Check if every item in a list satisfies a condition. Returns true only if all match.

Check if at least one item in a list satisfies a condition.

Add one or more items to the end of a list. Scalars are promoted to a list first.

Split a list into fixed-size chunks. The last chunk may be smaller.

Collect streaming pipeline data into a single in-memory value.

Extract the list of column names from a table or keys from a record.

Remove null values and empty strings from a list. For tables, removes rows containing any null.

Count the number of items in a list, rows in a table, or characters in a string.

Provide a fallback value for null or missing fields.

Describe the type and structure of a pipeline value.

Drop the last n items from a list or rows from a table. Defaults to 1.

Remove the last N columns from a table.

Remove a specific row by its 0-based index.

Apply a shell command to every item in a list. Returns a list of results.

Apply a closure to each item while the closure returns a non-null value. Stops on first null.

Check if a value is empty (empty string, list, or null).

Add a 0-based index to each item, returning records with index and item fields.

Select every Nth item from a list, starting at the first.

Filter items by a boolean condition expression.

Search for items containing a substring. Matches against any cell in tables, or string value in lists.

Get the first N items from a list or table (default: 1).

Flatten nested lists by one level. Non-list items and tables pass through unchanged.

Get a field value from a record or a full column from a table.

Group table rows into a record keyed by the distinct values of a specified column.

Treat the first row of a table as column headers, re-keying the remaining rows.

Insert a new column with a fixed value into every row of a table, or add a key to a record.

Check if a value is empty or null. Returns true for empty strings, lists, records, and null.

Check if a value is non-empty and non-null.

Iterate over key-value pairs of a record, applying a closure to each.

SQL-style inner join of two tables on a matching column.

Get the last N items from a list or table (default: 1).

Count items in a list, rows in a table, keys in a record, or characters in a string.

Split a string into a list of lines (split on newlines).

Merge two records (second wins on conflict) or concatenate two tables column-wise.

Move a column to a new position (before or after another column) in a table.

Get the item at a specific 0-based index.

Apply a closure to each item in parallel. Order is not guaranteed.

Add one or more items to the beginning of a list. Scalars are promoted to a list.

Generate a range of numbers as a list.

Reduce a list to a single value by applying an accumulator expression.

Remove one or more columns from a table. Rows are preserved with remaining columns.

Rename one or more columns in a table. Arguments are provided as old/new pairs.

Reverse the order of items in a list.

Rotate (transpose) table columns to rows and vice versa.

Select (project) specific columns from a table, discarding all others.

Randomly shuffle the items in a list.

Skip the first n items from a list or rows from a table. Defaults to 1.

Skip items until the condition first becomes true, then pass through all remaining.

Skip items while the condition is true, then pass through all remaining.

Extract a slice of a list by start and end index.

Sort a list in ascending order. Supports strings, numbers, and booleans.

Sort a table by one or more column values in ascending or descending order.

Take the first n items from a list or rows from a table. If n exceeds length, all items are returned.

Take items until the condition first becomes true. Stops collecting on first match.

Take items while the condition holds. Stops collecting on first non-match.

Transpose a table's rows and columns (pivot).

Remove consecutive duplicate values from a list. Sort first for full deduplication.

Remove duplicate rows from a table based on a specific column's values.

Update the value of an existing column in every row of a table, or update a key in a record.

Insert a column if missing, or update it if it exists.

Extract all values from a record as a list.

Filter rows from a table or items from a list by a condition expression.

Create a sliding window of fixed size over a list.

Wrap a scalar value into a single-field record.

Zip two lists together into a list of pairs.

Output an ANSI escape code by name. Useful for coloring or styling text.

Remove all ANSI escape codes from a string, leaving plain text.

Output a special character by name (newline, tab, etc.) or by Unicode code point.

Decode a base64-encoded string back to plain text.

Auto-detect column boundaries from whitespace-aligned text and convert to a table.

Encode a string to base64.

Parse a string using a pattern with named capture groups. Returns a table of matches.

Split a string into a list of individual characters.

Split a string into columns by a separator, assigning column names.

Split a list into sub-lists of a fixed size.

Split a string into a list of substrings using a delimiter.

Split a string into a list of words (split on whitespace).

Convert a string to camelCase. Splits on underscores, hyphens, and spaces.

Capitalize the first letter of a string, leaving the rest unchanged.

Check if a string contains a given substring. Returns "true" or "false" as a string.

Compute the Levenshtein edit distance between two strings.

Convert all characters in a string to lowercase.

Check if a string ends with a given suffix. Returns "true" or "false".

Find the 0-based index of the first occurrence of a substring. Returns -1 if not found.

Join a list of items into a single string using an optional separator.

Convert a string to kebab-case (lowercase words separated by hyphens).

Get the number of characters in a string.

Convert a string to PascalCase (UpperCamelCase).

Replace occurrences of a pattern in a string. Replaces only the first match by default.

Reverse the characters in a string.

Convert a string to SCREAMING_SNAKE_CASE (uppercase with underscores).

Convert a string to snake_case. Splits on hyphens, spaces, and camelCase boundaries.

Check if a string starts with a given prefix. Returns "true" or "false".

Count lines, words, characters, and bytes in a string.

Extract a substring by start and end character indices.

Convert a string to Title Case (capitalize the first letter of each word).

Remove leading and trailing whitespace from a string.

Convert all characters in a string to uppercase.

Evaluate a mathematical expression string. Supports +, -, *, /, %, **, parentheses.

Return the absolute value (magnitude without sign) of a number.

Compute the inverse cosine (arccosine) in radians.

Compute the inverse sine (arcsine) in radians.

Compute the inverse tangent (arctangent) in radians.

Compute the arithmetic mean (average) of all values in a list.

Round a float up to the nearest integer.

Compute the cosine of an angle in radians.

Return Euler's number (e ≈ 2.71828). A mathematical constant.

Compute e raised to the power of the input value (e^x).

Round a float down to the nearest integer.

Compute the natural logarithm (base e) of a value.

Compute the base-10 logarithm of a value.

Return the maximum value from a list.

Compute the median (middle value) of a sorted list. Averages two middle values for even-length lists.

Return the minimum value from a list.

Find the most frequently occurring value(s) in a list.

Return the mathematical constant Pi (π ≈ 3.14159).

Compute the product of all values in a list (multiply all together).

Round to the nearest integer (half rounds up).

Compute the sine of an angle in radians.

Compute the square root of a non-negative number.

Compute the standard deviation of a list of numbers.

Sum all values in a list. Supports integers and floats.

Compute the tangent of an angle in radians.

Compute the variance of a list of numbers.

Pad a value to a minimum width using a fill character.

Format a number as binary, hex, octal, or scientific notation.

Convert a value to its binary (byte sequence) representation.

Convert a value to boolean. Truthy: non-zero, non-empty. Falsy: 0, empty, null.

Convert a value (int or string) to a duration type.

Convert a number (bytes) to a human-readable filesize.

Convert a value to a floating-point number.

Convert a value to an integer. Strings are parsed, floats truncated.

Convert a list of key-value pairs or a table row into a record.

Convert any value to its string representation.

Perform a bitwise AND operation between two integers.

Perform a bitwise NOT (complement) on an integer.

Perform a bitwise OR operation between two integers.

Bitwise rotate left by n positions.

Bitwise rotate right by n positions.

Bitwise shift left by n positions (multiply by 2^n).

Bitwise shift right by n positions (divide by 2^n, truncated).

Perform a bitwise XOR (exclusive OR) between two integers.

Append bytes to the end of a byte sequence.

Extract byte(s) at a specific index or range from a byte sequence.

Build a byte sequence from a list of integers (0–255).

Collect individual bytes from a pipeline into a single byte sequence.

Check if a byte sequence ends with a given suffix.

Find the index of the first occurrence of a byte pattern.

Get the number of bytes in a byte sequence.

Remove a range of bytes from a byte sequence.

Replace a byte pattern with another in a byte sequence.

Reverse the order of bytes in a byte sequence.

Check if a byte sequence starts with a given prefix.

Extract the filename component from a path string.

Extract the directory component from a path string.

Check if a filesystem path exists.

Expand a path to its absolute form, resolving ~ and symlinks.

Join path components into a single path using the OS separator.

Parse a path string into a record with dir, stem, and extension components.

Compute the relative path from a base directory.

Split a path into a list of its components.

Determine the type of a filesystem path (file, dir, symlink).

Compute the MD5 hash of a string (hexadecimal digest).

Compute the SHA-256 hash of a string (hexadecimal digest).

Format a date value using strftime-style format specifiers.

Convert a date to a human-friendly relative string (e.g. '2 hours ago').

List all available timezone names.

Get the current date and time as a datetime value.

Convert a datetime to a record with year, month, day, hour, minute, second fields.

Convert a datetime to a table with year, month, day, etc. as columns.

Convert a datetime to a different timezone.

Generate a random boolean (true or false) with optional bias.

Generate a random string of alphanumeric characters.

Simulate rolling dice. Returns a list of results.

Generate a random floating-point number within an optional range.

Generate a random integer within a range.

Generate a random UUID v4 string.

Display a calendar for the current month or a specified month/year.

Generate an infinite or bounded sequence by repeatedly applying a closure to an accumulator.

Generate a numeric sequence from start to end with an optional step.

Generate a sequence of dates from start to end at a given interval.

Parse CSV text from the pipeline into structured table data.

Parse JSON text from the pipeline into structured data.

Parse TOML text from the pipeline into a record.

Parse TSV (tab-separated values) text from the pipeline into a table.

Parse XML text from the pipeline into structured data.

Parse YAML text from the pipeline into structured data.

Convert structured data to CSV text.

Convert structured data to an HTML table.

Convert structured data to JSON text.

Convert structured data to a Markdown table.

Convert a record to TOML text.

Convert structured data to TSV (tab-separated values) text.

Convert structured data to XML text.

Convert structured data to YAML text.

List all environment variables as a structured table with name and value columns.

Load a record of key-value pairs into the environment as variables.

Show a debug text representation of pipeline data, useful for inspecting types and structure.

Display detailed shell build and runtime information (version, features, OS, etc.).

Inspect the pipeline value in an interactive detailed view.

Show metadata about a pipeline value including its type, span, and source origin.

Measure and report the wall-clock execution time of an expression or block.

View the source code of a user-defined command, alias, or function.

Copy files and directories from source to destination.

Calculate and display disk usage for a path.

Expand a glob pattern into a list of matching file paths.

Create one or more directories, including intermediate parents.

Move or rename files and directories.

Open and auto-parse a file based on its extension (JSON, TOML, YAML, CSV, etc.).

Remove files and directories.

Save pipeline data to a file, optionally appending.

Create a new empty file or update the timestamp of an existing file.