Install Quirl

Homebrew

brew install niklas-heer/tap/quirl
quirl --version

The tap provides Quirl 0.5.1. Confirm quirl 0.5.1 before following the current walkthrough. To upgrade an existing Homebrew installation:

brew update
brew upgrade niklas-heer/tap/quirl
quirl --version

The formula selects a SHA-256-pinned native binary for macOS or Linux on ARM64 or x86_64. It installs quirl plus its redistribution license files; its bounded offline test does not download the completion database or command model.

Start and leave a session

After installation, check the binary and start Quirl from your existing terminal:

quirl --version
quirl

You start in Normal mode. Follow your first session for a complete command-and-data example. Press Ctrl-D on an empty input line to leave Quirl and return to your previous shell; Ctrl-C clears unfinished input. Trying Quirl this way does not change your login shell.

To remove the Homebrew installation, leave Quirl and run this in your previous shell:

brew uninstall quirl

Your Quirl configuration, history, and downloaded data are stored separately from the installed binary.

Use Quirl as your login shell

Once Quirl feels right for whole sessions, you can make it your login shell. Programs that start your shell for their own work keep working, because Quirl runs their POSIX code in /bin/sh unchanged. This covers ssh host command, scp, rsync, Git over SSH, editors reading your environment with $SHELL -l -i -c, and coding agents using $SHELL -c.

command -v quirl | sudo tee -a /etc/shells
chsh -s "$(command -v quirl)"

A login session takes its environment from /etc/profile and ~/.profile, including macOS path_helper entries. Quirl does not read ~/.zprofile or ~/.zshrc, so move variables you need everywhere, such as PATH additions, into ~/.profile. Setup lines like eval "$(brew shellenv)" work there and at Quirl's prompt.

To switch back, run chsh -s /bin/zsh (or your previous shell).

Direct release archive

Download the package for your operating system and architecture from the v0.5.1 GitHub Release, verify it against SHA256SUMS, and compare the entry in release-manifest-v1.json before putting quirl on PATH. Never use an asset from a mutable branch URL as a release binary.

Nix flake

With Nix flakes on Linux or Apple Silicon macOS, build and install the latest main from source:

nix profile add github:niklas-heer/quirl
quirl --version

main may be ahead of the supported release. Like Homebrew, the flake installs only the binary; completion and model assets download on demand.

Binary requirements

The native package needs only a supported Linux or macOS host. It does not require Git, Rust, Python, or a system Lua installation.

Source-build requirements

• Linux or macOS for the supported interactive experience.
• Git.
• Rustup. The repository pins Rust 1.99.0 with clippy and rustfmt.
• Python 3 only for the Unix PTY quality gate.

You do not need a system Lua installation. Quirl 0.5.1 embeds vendored Lua 5.5.1. Historical v0.1.0 artifacts retain Lua 5.4.

Build and run

git clone https://github.com/niklas-heer/quirl.git
cd quirl
cargo run -p quirl-cli

For contributors who have cloned the repository and installed the Homebrew release, this optional text-only tour runs against that installed release:

cargo xtask demo

The first-session walkthrough works with just the installed binary and does not require a checkout or Rust.

This preserved text tour documents an earlier 0.1-era build, including its local AI workflow and Lua 5.4 runtime. For v0.5.1, follow the first-session guide or watch the current recording.

Verify a checkout

The canonical local quality gate formats, lints, tests, and validates the workspace's generated artifacts:

cargo xtask check

See Contributing for focused checks and the complete test strategy.

Downloadable data and offline use

The completion SQLite database and command model are separate exact-version assets, not part of the binary or Homebrew package. The website channel may advance completion knowledge independently without cutting a binary release; each database and required license notice has immutable, digest-named bytes and its own source identity, while the compatible model record is retained. Missing assets never delay the first prompt: Quirl uses built-in/local completion and degraded natural-command retrieval while a bounded background update is eligible.

Inspect or explicitly retry asset work with:

quirl assets status
quirl assets retry
quirl assets update

On macOS, admitted assets live below ~/Library/Application Support/quirl/assets. On Linux, they live below $XDG_DATA_HOME/quirl/assets, or ~/.local/share/quirl/assets when XDG is not set. Retry metadata uses the matching quirl/assets platform cache directory. A failed update does not replace an already valid generation.