# lmcomplete / `lmc`
`lmcomplete` is a context-aware shell command helper for turning natural-language requests into shell commands and short explanations. The `lmc` binary uses your shell, current directory, git state, and recent command history to produce tighter results than a plain prompt.
It is intentionally small and opinionated in v1:
- `lmc "..."` is shorthand for `lmc expand "..."`
- `expand` returns a shell command only
- `explain` returns a concise plain-text explanation
- `audit` prints the prompt bundle without calling the provider
- `init zsh` prints the zsh widget script
- `stats` shows stored usage stats
## Supported Scope
Launch support is intentionally narrow:
- macOS-first
- zsh-first
- OpenRouter-only
- no auto-execution
`lmc` prints commands. It does not run them for you.
## Install
From crates.io after release:
```sh
cargo install lmcomplete
```
From a local checkout:
```sh
cargo install --path .
```
Build from source during development:
```sh
cargo build
```
## Quickstart
1. Set your OpenRouter API key:
```sh
export OPENROUTER_API_KEY="your-key-here"
```
2. Build or install `lmc`.
3. Add the zsh widget to your shell startup:
```sh
eval "$(lmc init zsh)"
```
4. Ask for a command:
```sh
lmc "show git status"
```
5. Use the explicit commands when you want to be precise:
```sh
lmc expand "commit all changes with message fix login" --shell zsh --history 0
lmc explain "tar xzf archive.tar.gz" --shell zsh --history 0
```
## Config And Auth
`lmc` reads an optional TOML config file from the XDG config location. By default that is:
- `~/.config/lmcomplete/config.toml`
If `XDG_CONFIG_HOME` is set, `lmc` uses `$XDG_CONFIG_HOME/lmcomplete/config.toml` instead.
You can also point at a specific file:
```sh
lmc --config /path/to/config.toml stats
```
The canonical documented example lives in [`docs/config.example.toml`](docs/config.example.toml).
Set the API key in the environment or in config:
```sh
export OPENROUTER_API_KEY="your-key-here"
```
If you store the key in the config file, keep it private. On Unix, `lmc` expects the file mode to be `0600`.
## Examples
Return a command:
```sh
lmc expand "show git status" --shell zsh --history 0
```
Explain a command:
```sh
lmc explain "tar xzf archive.tar.gz" --shell zsh --history 0
```
Inspect the prompt bundle without calling the provider:
```sh
lmc audit 'curl -H "Authorization: Bearer sk-secret-value" https://example.com' --shell zsh --history 0
```
Show current usage stats:
```sh
lmc stats
```
Initialize the zsh widget:
```sh
lmc init zsh
```
## Safety And Privacy
`lmc` sends the minimum context needed for a better completion: shell, operating system, cwd-derived project info, git state, and recent shell history when available.
Secret-like values are redacted before prompts are sent. The `audit` command lets you inspect the final prompt bundle locally without making a provider request.
The tool also keeps a hard line on execution: it suggests commands, it does not run them.
## Troubleshooting
If you see `missing provider API key`, export `OPENROUTER_API_KEY` or add `api_key` under `[provider]` in your config file.
If you see `config file ... must have mode 0600`, tighten the file permissions on Unix:
```sh
chmod 600 ~/.config/lmcomplete/config.toml
```
If `init zsh` does nothing after you run it, add `eval "$(lmc init zsh)"` to `~/.zshrc`, then restart zsh or source the file.
If `expand` or `explain` returns an error about the provider, check network access, the OpenRouter API key, and the model configuration in your config file.
## Changelog
See [CHANGELOG.md](./CHANGELOG.md) for release notes.
See [docs/launch/terminal-demo-plan.md](./docs/launch/terminal-demo-plan.md) for the launch demo script.