AI in your
terminal.
Chat, write code, edit files, and execute autonomous agentic tasks — without leaving the terminal you already live in. 40+ models. One command to install.
$ npm install -g lumichat-cli $ lumi login ✓ Opened browser — sign in to continue ✓ Authenticated as dev@example.com $ lumi do "add input validation to all route handlers" ◆ Reading src/routes/users.ts ◆ Reading src/routes/posts.ts ⚡ Write file: src/routes/users.ts Run this? [y/N] y ✓ Done — 3 files updated, 12 validators added
Installation
Requirements
curl -fsSL https://lumichats.com/install.sh | bash
The script checks for Node.js ≥ 18, installs lumichat-cli globally via npm, and verifies the binary is in your PATH. Takes about 30 seconds.
Or install manually via npm
npm install -g lumichat-cli
Verify the installation
lumi --version # 1.3.1 lumi # Prints full help and available commands lumi login # Opens browser → authenticate → you're ready
Quick Start
Common workflows to get you productive in the first 5 minutes.
Chat with AI
lumi chat # Start an interactive session > What's the difference between useEffect and useLayoutEffect in React? # → Full streamed answer with syntax-highlighted code examples
Get a quick answer and exit
lumi ask "explain the CAP theorem in 2 sentences"
Review a code file
lumi code src/api.ts "are there any security issues in this file?"
Let the AI edit a file (always shows diff first)
lumi edit utils.ts "add JSDoc to all exported functions" --model qwen-coder
Run an autonomous agentic task
lumi do "find all TODO comments in src/ and fix the obvious ones"
Pipe shell output to the AI
npm test 2>&1 | lumi ask "what's failing and why?"
Command Reference
Click any command to expand its full syntax, all options, and examples.
Quick Reference Card
lumi login Sign in (opens browser) lumi logout Sign out lumi chat Interactive chat lumi chat --model <name> Chat with a specific model lumi ask "<question>" One-shot answer, then exits lumi ask "<q>" --file <path> Attach a file cat file | lumi ask "<q>" Pipe content as context lumi ask "<q>" > out.txt Clean plain-text to file lumi code <file> Code chat with file context lumi code <file> "<question>" Open with initial question lumi edit <file> "<task>" AI edits file (diff first) lumi do "<task>" Autonomous agentic task lumi do "<task>" --yes Skip all confirmations lumi project Load current folder lumi project <folder> --depth 3 Shallow scan lumi run <cmd> Run a command lumi run --analyse <cmd> Run + auto-send output to AI lumi models List all 40+ models lumi status Account and usage info lumi upgrade Open pricing page
Agentic Mode — lumi do
lumi do gives the AI a set of filesystem and shell tools and lets it execute a task autonomously — reading files, writing changes, running commands, and adapting based on the results. Every destructive operation requires your explicit confirmation before anything touches disk or your shell.
Available tools
| Tool | Access level | Description |
|---|---|---|
| read_file | Read-only | Read the full contents of any file in the project tree |
| read_file_lines | Read-only | Read a specific line range — efficient for large files |
| list_files | Read-only | List directory contents with smart dotfile filtering |
| write_file | Destructive ⚠ | Write or overwrite a file — always prompts [y/N] unless --yes |
| patch_file | Destructive ⚠ | Apply a line-level patch — always prompts [y/N] unless --yes |
| execute_command | Destructive ⚠ | Run a shell command — always prompts [y/N] unless --yes |
How confirmation works
$ lumi do "write unit tests for src/auth.ts" ◆ Reading src/auth.ts (no prompt — read-only) ◆ Reading src/types.ts (no prompt — read-only) ⚡ Write file: src/auth.test.ts (48 lines) Run this? [y/N] y ✓ src/auth.test.ts created ✓ Task complete — 1 file written, 12 tests added
--yes (-y) to auto-approve all confirmations. Use this only in fully automated pipelines where you trust the task and the project scope. For interactive use, the default prompt is your safety net.Real-world examples
# Fix failing tests lumi do "run npm test and fix any failing unit tests" # Add documentation lumi do "add JSDoc to all exported functions in src/" # Security audit + fix lumi do "find any SQL injection risks in src/db/ and patch them" # Refactor with confidence lumi do "refactor src/auth.ts to use async/await throughout" # Generate from scratch lumi do "generate a CHANGELOG.md from git log --oneline" # Automate in CI (all confirmations auto-approved) lumi do "generate API docs from src/routes/" --yes
Model Reference
Pass any of these shortnames to --model (or -m) in any command. Run lumi models to see the full current list with Pro/Free labels.
| Shortname | Model |
|---|---|
| best | Best available model for the prompt (auto-selected) |
| claude | Claude Sonnet (balanced reasoning + coding) |
| claude-fast | Claude Haiku (fast, cheaper) |
| qwen-coder | Qwen2.5-Coder 32B — strongly recommended for coding tasks |
| gpt4o | GPT-4o |
| gpt4o-mini | GPT-4o Mini (fast) |
| gemini | Gemini 1.5 Pro |
| gemini-flash | Gemini 1.5 Flash (fast) |
| llama | Llama 3.1 70B (open source) |
| mistral | Mistral Large |
| deepseek | DeepSeek R1 (strong at maths and reasoning) |
| o1-mini | OpenAI o1-mini (extended thinking) [Pro] |
qwen-coder for all code editing and agentic tasks. Use claude for reasoning, writing, and analysis. Use best to let Lumi pick automatically.Slash Commands
Type these inside any interactive session (chat, code, project). Tab completion works for most slash commands.
Universal — all session types
Project-only — inside lumi project
Keyboard shortcuts
Configuration
Lumi stores a single config file. You should never need to edit it manually — lumi login and lumi logout manage it for you.
File location
~/.lumichat/config.json # Permissions: -rw------- (0600 — only your user can read it)
Schema
| Field | Type | Description |
|---|---|---|
| accessToken | string | Short-lived JWT for API calls |
| refreshToken | string | Long-lived token used to obtain new access tokens |
| userId | string | Your account UUID |
| string | Account email (display only) | |
| plan | string | Current plan: "free" | "pro" |
| expiresAt | number | UNIX timestamp (ms) when the accessToken expires |
~/.lumichat/config.json to version control or share it. It contains your auth tokens. For CI/CD, see the CI/CD section below.Token lifecycle
Access tokens are short-lived JWTs. Lumi checks expiresAt before every API call and proactively refreshes using the refreshToken when the access token is within 60 seconds of expiry. You will never see an "auth expired" error mid-session in normal usage.
Security & Safety
Lumi is designed so that even a misbehaving or adversarially-prompted model cannot harm your system without your explicit approval.
Path traversal protection
All file operations in lumi do are gated by an assertInBounds() check. Every resolved path is verified to be inside the current working directory tree. If the model attempts to read ~/.ssh/authorized_keys or any path outside the project, the operation is blocked with an error — even if the model was tricked into requesting it via prompt injection.
Human-in-the-loop for destructive actions
Before any write_file, patch_file, or execute_command, Lumi prints exactly what the agent intends to do and asks for explicit [y/N] confirmation. Read-only operations (read_file, list_files) never prompt. If you deny an operation, the agent receives a structured "user denied this operation" result and can adapt its approach — it won't crash or get stuck.
Credential storage
~/.lumichat/config.json is created with 0600 permissions (owner read/write only). The file is validated on load against a strict JSON schema — a malformed or tampered file will cause a clean error, not silent misbehaviour.
CSRF protection during login
The OAuth callback includes a CSRF nonce that is verified before accepting any credentials. A malicious page cannot trigger an unwanted login by making requests to the local callback server.
--yes flag bypasses all confirmation prompts and should only be used in pipelines where you fully trust the task description and the project scope. Never use --yes when running lumi do on an unfamiliar repository.CI / CD & Automation
Lumi works well in automated pipelines. The key is writing a valid config.json from secrets before running any command.
GitHub Actions — basic setup
# .github/workflows/lumi.yml
jobs:
lint-with-ai:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
- name: Install Lumi CLI
run: npm install -g lumichat-cli
- name: Write credentials
run: |
mkdir -p ~/.lumichat
echo '${{ secrets.LUMICHAT_CONFIG }}' > ~/.lumichat/config.json
chmod 600 ~/.lumichat/config.json
- name: Run agentic task
run: |
lumi do "generate API docs from src/routes/" --yesGenerating the config secret
# On your local machine, after lumi login: cat ~/.lumichat/config.json # Copy the JSON → add as LUMICHAT_CONFIG secret in GitHub # Note: access tokens expire. Use a long-lived refresh token setup, # or re-generate the config periodically using lumi login.
Pipe output in shell scripts
#!/usr/bin/env bash # lumi ask strips ANSI when stdout is not a TTY SUMMARY=$(lumi ask "summarise this diff" --file changes.diff) echo "$SUMMARY" >> release-notes.md # Analyse test results lumi ask "what failed and why" --file test-output.txt > diagnosis.txt
config.json (including refreshToken) so that token refresh works automatically. Avoid storing only the accessToken — it will expire within minutes.Plans & Limits
| Feature | Free | Pro |
|---|---|---|
| Messages per day | 5 | Unlimited |
| Model access | Free-tier models | All 40+ including Premium |
| lumi chat | ✓ | ✓ |
| lumi ask | ✓ | ✓ |
| lumi code | ✓ | ✓ |
| lumi edit | ✓ | ✓ |
| lumi do (agentic mode) | ✓ (counts each tool call) | ✓ Unlimited |
| lumi project | ✓ | ✓ |
| Piped / non-TTY output | ✓ | ✓ |
| Streaming | ✓ | ✓ |
| Premium models (o1, etc.) | ✗ | ✓ |
lumi upgrade to open it in your browser.Troubleshooting
Ready to start?
Install, sign in, and you're chatting in under 60 seconds.
npm install -g lumichat-cli && lumi login