CLI Reference
lacy is the command you run outside the plugin: install it, check it, point it at a different AI tool, read the query log. It is pure bash with no dependencies, installed to ~/.lacy/bin/lacy.
For the commands Lacy intercepts inside your shell — mode, tool, ask, /new, quit — see the Commands Reference.
Every command
Run lacy with no arguments to open a subshell with Lacy loaded. Run lacy help to print this list in your terminal.
Install and update
| Command | What it does |
|---|---|
lacy install | Install Lacy Shell. Adds the source line to your rc file and ~/.lacy/bin to your PATH. |
lacy update | Move to the latest release. Keeps your config.yaml. |
lacy reinstall | Fresh copy of the latest release. Also keeps your config.yaml. |
lacy uninstall | Remove Lacy Shell. Asks for confirmation when run from a terminal. |
Check and configure
| Command | What it does |
|---|---|
lacy setup | Change the AI tool, the default mode, or any config value, interactively. |
lacy status | Install path, version, whether your rc file is wired up, the active AI tool, and which AI CLIs it can find. |
lacy doctor | Check for the six things that usually break an install. Exits 1 if any check fails. |
lacy config | Print ~/.lacy/config.yaml. See the flags below for edit and path. |
Sessions, logs, and info
| Command | What it does |
|---|---|
lacy new | Forget the saved agent session. The next question starts a fresh conversation. |
lacy resume | Print the saved session’s tool and id, so you can pick it up in another shell. |
lacy logs | Show the last 50 logged queries. Off unless you enable it (see below). |
lacy changelog | Fetch and print the latest release notes. |
lacy info | A short introduction to what Lacy does and how to try it. |
lacy completions | Print a shell completion script. Defaults to your current shell. |
lacy version | Print the installed version. |
lacy help | Print every command, the in-shell commands, and the environment variables. |
Flags and arguments
Three commands take arguments:
lacy config # print config.yaml
lacy config path # print the path to config.yaml
lacy config edit # open it in $EDITOR (falls back to $VISUAL, then vi)
lacy logs # last 50 queries
lacy logs 200 # last 200 queries
lacy logs all # every query
lacy logs --count # how many queries are logged
lacy logs --clear # delete the log file
lacy completions zsh # print the zsh completion script
lacy completions bash # print the bash completion scriptTo keep completions, write the script somewhere your shell loads it:
# zsh — a directory you own, added to fpath before compinit
mkdir -p ~/.zsh/completions
lacy completions zsh > ~/.zsh/completions/_lacy
# then in ~/.zshrc, above compinit:
# fpath=(~/.zsh/completions $fpath)
# bash
mkdir -p ~/.local/share/bash-completion/completions
lacy completions bash > ~/.local/share/bash-completion/completions/lacyShort forms
The dispatcher accepts these aliases. The session commands take a leading slash too, so the muscle memory you build inside Lacy still works outside it.
| Command | Also accepts |
|---|---|
lacy status | lacy s |
lacy config | lacy c, lacy config show |
lacy version | lacy -v, lacy --version |
lacy help | lacy -h, lacy --help |
lacy new | reset, clear, and each with a slash: /new, /reset, /clear |
lacy resume | lacy /resume |
lacy logs --clear | lacy logs -c |
Query logging is off by default
lacy logs has nothing to show until you turn logging on. Lacy does not record your questions unless you ask it to.
# ~/.lacy/config.yaml
logging:
queries: trueOnce enabled, each query is appended to ~/.lacy/logs/queries.log as a tab-separated line of timestamp, tool, and the raw query. No terminal context is written. The directory is 0700 and the file is 0600, and the log is trimmed to the last 1000 lines once it passes 1 MB.
When update and reinstall refuse
Both commands rewrite ~/.lacy, so they stop rather than clobber an install they did not create:
If ~/.lacy is | Update instead with |
|---|---|
| A symlink created by Homebrew | brew upgrade lacymorrow/tap/lacy |
| A symlink to your own git checkout | git pull in that checkout |
| A git checkout with uncommitted changes | Commit or stash first, then run lacy update |
What doctor checks
lacy doctor is the first thing to run when Lacy is installed but nothing happens. It checks, in order:
- The plugin file exists in
~/.lacy - Your rc file has an uncommented source line for it
- Bash users are on Bash 4 or newer (macOS ships 3.2, which Lacy refuses)
config.yamlexists- The configured AI tool is on your PATH, or auto-detect can find one
~/.lacy/binis on your PATH
Every failed check prints the command that fixes it. The exit code is 1 if anything failed, so you can use it in a script. For the longer list of symptoms and causes, see Troubleshooting.
The Node UI, and skipping it
setup, install, and uninstall try npx --yes lacy@latest first, which gives you the @clack/prompts interface. If Node is missing or the fetch fails, they fall back to the bash implementation and behave the same way.
LACY_NO_NODE=1 lacy setup # bash prompts, no npx round-tripEnvironment variables
| Variable | Effect |
|---|---|
LACY_NO_NODE=1 | Never shell out to npx. Use the bash path everywhere. |
NO_COLOR=1 | Plain output, no escape sequences. TERM=dumb does the same. |
LACY_REF | Install a specific tag or branch instead of the newest release. |
DO_NOT_TRACK=1 | Send no telemetry. LACY_NO_TELEMETRY=1 does the same. |
Lacy reports an anonymous event when it is installed, updated, or removed, and one first_load event the first time the plugin loads. Never your queries, never your commands. The full list is on the privacy page.
Next
- Commands Reference — the commands that work inside your shell, once Lacy is loaded.
- Configuration — every key in
config.yaml. - Troubleshooting — when
lacy doctorpasses but something still feels wrong.