Your first session

This guide uses Quirl 0.5.1, available through Homebrew and verified native archives. Check quirl --version first; see the installation guide to install or upgrade.

This walkthrough works from any directory, needs no sample files or account, and leaves your login shell unchanged. Install Quirl, then run this from your current shell:

quirl

Quirl starts in Normal mode. Enter the following commands one line at a time; the prompt tells you which mode is active.

Run a familiar pipeline

printf '%s\n' hello | tr a-z A-Z

You should see:

HELLO

Normal mode runs familiar programs and byte pipelines. You can also use pwd, cd, and your usual external commands.

Filter records in Data mode

Type this and press Enter:

mode data

Then paste the following pipeline. The two deployment records are included, so there is no file to create or download:

[{"service":"api","region":"eu","status":"failed"},{"service":"web","region":"us","status":"ok"}] | where status == "failed" | select service region

where keeps the failed deployment and select chooses the fields to show. Interactive streams print one record per line as results arrive:

{"service":"api","region":"eu"}

When you have your own JSON or CSV file, replace the initial list with open "your-file.json" or open "your-file.csv". Learn more in the typed data guide.

Return to Normal mode and find help

mode normal

You are ready to run ordinary commands again. Type help for an overview, then try help mode or help quirl data for a specific contract.

• Tab completes like Zsh: a unique match is inserted, several matches extend to their shared prefix and open a menu, and Shift-Tab expands the menu into the picker. See completion.
• F1 opens contextual command documentation.
• Ctrl-R or Up searches your command history.
• Alt-Q, then f, opens the file picker.
• Alt-Q, then g, opens the project picker. Discovery runs in the background; choosing a repository changes directory and keeps unfinished input.

Alt-Q, then d or n, also switches to Data or Normal mode. The textual mode data and mode normal commands work when your terminal does not pass the shortcut through.

To leave Quirl, press Ctrl-D on an empty input line. You return to the shell that launched it. Press Ctrl-C first if you need to clear unfinished input.

Use typed data without entering Quirl

From Bash, Zsh, or your existing shell, pass the entire pipeline as one quoted argument:

quirl data '[{"service":"api","region":"eu","status":"failed"},{"service":"web","region":"us","status":"ok"}] | where status == "failed" | select service region'

The standalone quirl data command defaults to a table and returns to your existing prompt:

╭───┬─────────┬────────╮
│ # │ service │ region │
├───┼─────────┼────────┤
│ 0 │ api     │ eu     │
╰───┴─────────┴────────╯

Add --format plain to print the same record-per-line output as the interactive pipeline.

Optional: ask AI for a proposal

AI planning requires an installed, authenticated Codex CLI. It sends your submitted intent and bounded command-catalog context to OpenAI; normal commands and Data mode do not need it.

In Quirl, type mode ai, or press Alt-Q, then i. Describe a task such as “find the largest files in this directory” and press Enter. In the default rich editor, type a follow-up and press Enter to continue the conversation. When a proposal is ready, Tab or Enter on empty input transfers it to Normal mode for review. A separate Enter executes the reviewed command. Esc cancels planning or closes the conversation. There is no local planner fallback when Codex is unavailable.

The local completion database serves ordinary completion and the separate quirl ai search tool. AI planning does not require Quirl's downloaded local model.

When familiar shell syntax needs Bash or Zsh

Quirl's native grammar supports a focused set of quoting, redirects, byte pipelines, and command lists. For loops, functions, here-documents, and other shell-specific syntax, use an explicit Bash or Zsh island. For example, in Normal mode:

bash { for name in api web; do printf '%s\n' "$name"; done }

This prints api and web on separate lines.

The default rich terminal surface rejects background pipelines before starting them. For classic background jobs with inherited terminal output, use ui.surface = "simple"; see terminal behavior. Lua is a separate scripting surface, not an interactive mode. For example, quirl eval '1 + 2' prints 3.