Getting started
On macOS or Linux, the install script puts blitz, blitzd and blz in ~/.local/bin, after checking the archive against the release’s signed checksums (the signature itself when cosign is installed):
curl -fsSL https://github.com/retail-cortex/blitz/releases/latest/download/install.sh | sh
BLITZ_BIN picks another folder, BLITZ_VERSION=v0.7.1 a particular release (the latest without it), and BLITZ_REQUIRE_SIGNATURE=1 refuses to install without checking the signature. With Homebrew: brew install retail-cortex/tap/blitz.
Later, blitz update installs the latest release over this one (--check only says whether there is one). It checks the release’s signature and its checksum itself, with nothing else to install (releases before v0.7.0 need cosign for their signature). A copy installed by Homebrew is updated with brew upgrade blitz.
Or download the archive for your platform from the releases. Each holds blitz, blitzd, the blz shortcut (a link to blitz, not on Windows), and the license files; Windows’s also has blitz-tray.exe, which runs the service and opens the desktop app’s page:
| Platform | Archive |
|---|---|
| macOS, Apple silicon | blitz_<version>_darwin_arm64.tar.gz |
| macOS, Intel | blitz_<version>_darwin_amd64.tar.gz |
| Linux, x86-64 | blitz_<version>_linux_amd64.tar.gz |
| Linux, ARM64 | blitz_<version>_linux_arm64.tar.gz |
| Windows, x86-64 | blitz_<version>_windows_amd64.zip |
Unpack it and put its folder on your PATH. The desktop app comes separately: Blitz_<version>_macos_arm64.dmg (Apple silicon) or _x64.dmg (Intel), Blitz_<version>_windows_x64_setup.exe (it installs Blitz for you, no administrator needed) or Blitz_<version>_windows_x64.zip (unzip it and run Blitz.exe), or for Linux blitz-desktop_<version>_<arch>.deb for Ubuntu 24.04, Debian 13 and later (sudo apt install ./blitz-desktop_*.deb), the Arch package, or the tarball.
The macOS command-line binaries aren’t notarized, so a copy downloaded in a browser is quarantined and Gatekeeper won’t run it. Clear the flag with xattr -d com.apple.quarantine blitz blitzd, or open it once through Finder’s context menu.
To build from source instead, see building.
Each release has a checksums.txt, signed with cosign (keyless, through GitHub’s OIDC), and an SPDX SBOM per archive. Check the signature against this repository’s release workflow, then the checksums:
cosign verify-blob --bundle checksums.txt.sigstore.json \
--certificate-identity-regexp '^https://github.com/retail-cortex/blitz/\.github/workflows/release\.yml@refs/tags/v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt
sha256sum --ignore-missing -c checksums.txt
The desktop packages each have their own bundle: cosign verify-blob --bundle <file>.sigstore.json with the same flags, then the file.
blitz config init # writes a commented ~/.blitz/.env.toml (owner-only)
blitz config set-key gemini # stores the key in the OS keychain
blitz doctor # checks the settings, credentials, sandbox, MCP servers and hooks
llm.provider picks the provider: gemini (the default), anthropic, openai or ollama. A key can also come from the environment (GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY). Settings are read only from ~/.blitz, never from the project, so a cloned repository can’t redirect your key or turn off approvals. Configuration has the details.
On Linux, the shell sandbox is required. Install bubblewrap (sudo apt install bubblewrap) and run blitz security: it says whether bubblewrap runs. On Ubuntu 24.04 and later, AppArmor restricts the user namespaces it needs; blitz security fix-apparmor (or Allow bubblewrap in the desktop app) installs an AppArmor profile that lets bwrap alone have them, asking for your password once. Until the sandbox works, workspaces don’t open; to run the agent’s commands unsandboxed instead, set [sandbox] shell = "auto" in ~/.blitz/.env.toml.
cd ~/src/project
blitz # an interactive session
blitz "why does the build fail?" # one prompt, then exit
In a session, type a request. Blitz reads and searches the workspace, shows a diff before each edit and asks before commands run; answer y (once), s (for the session), a (always) or n. /undo puts back what the last turn changed, and /help lists the commands.
blitz service install # starts blitzd at every login (launchd or systemd)
With the service running, blitz attaches to it, the desktop app works, and workers run on their schedules.
In a new folder, run /setup (in the desktop app’s chat, or in a session): it asks what the project is for and writes its specification, then fits the workspace to it, for software, research, data analysis or writing. /spec on its own writes or revises the specification. Start any project: spec, then setup shows each.