Installation

The Expensicat CLI is distributed as a native binary for macOS, Linux, and Windows. You can run it one-off via npx, install it globally with npm, or download the binary directly.

npx (no install)

Run any command without installing — npx downloads and caches the binary automatically:

npx @expensicat/cli@latest login
npx @expensicat/cli@latest invoice list

Useful for CI pipelines, one-off scripts, and trying things out.

Global install (recommended)

Install once, run as expensicat:

npm install -g @expensicat/cli

Then:

expensicat --help
expensicat login
expensicat whoami

This pulls the correct platform binary automatically via npm's optionalDependencies. Supported platforms:

darwin-arm64 (Apple Silicon)
darwin-x64 (Intel Mac)
linux-x64
linux-arm64
windows-x64
windows-arm64

If you installed via npm i -g, the CLI updates itself automatically — on startup it checks the npm registry once a day, and when a newer version is released it spawns a detached npm install that completes in the background. Your current command keeps running on the current binary; the new version takes effect on your next invocation.

Opt out any time with --no-auto-update (one-shot), EXPENSICAT_DISABLE_AUTOUPDATER=1 (shell), or auto_update = false in ~/.expensicat/config.toml (persistent). See Configuration → Updating for details.

Force a check and upgrade immediately with:

expensicat upgrade

For direct-binary or brew installs the CLI only notifies — follow the instructions below.

npx

Always runs the version you specify. Use @latest to force a refresh:

npx @expensicat/cli@latest --version

Global install

npm update -g @expensicat/cli

Or reinstall to force the latest version:

npm install -g @expensicat/cli@latest

Check your installed version:

expensicat --version

Direct binary download

If you'd rather not use npm, download the binary for your platform from GitHub Releases, then place it on your PATH:

# macOS / Linux
chmod +x expensicat
sudo mv expensicat /usr/local/bin/

# Verify
expensicat --version

Shell completion

Generate completion scripts for your shell:

# bash — add to ~/.bashrc
expensicat completion bash >> ~/.bashrc

# zsh — add to ~/.zshrc
expensicat completion zsh >> ~/.zshrc

# fish — add to ~/.config/fish/completions/
expensicat completion fish > ~/.config/fish/completions/expensicat.fish

Restart your shell to pick up the changes.

Uninstall

npm uninstall -g @expensicat/cli

Config and credentials live in ~/.expensicat/. Remove that directory to fully clean up:

rm -rf ~/.expensicat