Getting Started

Install LeanCTL and start coding with AI in under 5 minutes. Works on macOS, Linux, and Windows.

Install

Choose your preferred installation method:

Universal installer (recommended)

The fastest way — works on macOS, Linux, and WSL:

curl -fsSL https://leanctl.com/install.sh | sh

The script detects your OS and architecture, downloads the correct binary, and places it in /usr/local/bin.

npm

Install the pre-built binary via npm — no Rust toolchain required:

npm install -g leanctl-bin

Downloads the correct binary for your platform during postinstall.

AUR (Arch Linux)

yay -S leanctl-bin

Manual download

Download binaries for your platform from GitHub Releases.

After downloading, extract and move to your PATH:

# macOS / Linux
tar xzf leanctl-*.tar.gz
chmod +x leanctl
sudo mv leanctl /usr/local/bin/

# macOS: remove Gatekeeper quarantine if needed
xattr -d com.apple.quarantine /usr/local/bin/leanctl

First-Time Setup

After installing, run the interactive setup wizard:

leanctl init

The wizard walks you through:

• Choosing a provider (Ollama, Anthropic, OpenAI, DeepSeek, Groq, OpenRouter)
• Entering your API key (or using environment variables)
• Selecting a default model
• Configuring thinking behavior

Quick start with Ollama (free)

# 1. Install Ollama (ollama.com)
# 2. Pull a model
ollama pull qwen3.5:27b

# 3. Run leanctl
leanctl init    # choose "ollama"
leanctl         # start coding

Quick start with API keys

If you already have API keys, LeanCTL auto-detects them from environment variables:

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...
# Or: export OPENAI_API_KEY=sk-...

# Start coding
leanctl

Your First Session

Start LeanCTL in any project directory:

cd your-project
leanctl

LeanCTL launches a full-screen TUI (Terminal User Interface). Type your request and press Enter:

# Example prompts
"fix the failing tests"
"add input validation to the signup form"
"refactor the auth module for better error handling"

LeanCTL will read your files, execute commands, make edits, and run tests — all with your approval.

Attach files with @

Reference files directly in your prompt:

@src/auth.ts please fix the token expiry bug

Run inline commands with !

Attach shell output to your prompt:

!npm test — fix the failing tests

Keyboard essentials

See the full keyboard reference in TUI Commands.

CLI Modes

Interactive (default)

leanctl                # new session
leanctl -C             # continue last session
leanctl --yolo         # auto-approve all tool executions

Non-interactive

leanctl run -p "add tests for auth.ts"
leanctl run -p "fix the linting errors" --model claude-sonnet-4-20250514

Utility commands

leanctl models         # list configured providers
leanctl sessions       # list past sessions
leanctl stats          # show token savings
leanctl config         # show current config
leanctl status         # show plan, provider, gateway status
leanctl logs           # view application logs

Updating

LeanCTL checks for updates automatically and notifies you when a new version is available. To update:

# Same as initial install
curl -fsSL https://leanctl.com/install.sh | sh

# Or via npm
npm update -g leanctl-bin

# Or via AUR
yay -Syu leanctl-bin

Next Steps

• Configuration — customize behavior, display, thinking
• Providers — set up Anthropic, OpenAI, Ollama, and more
• Agent Tools — 23 built-in tools the AI uses
• TUI Commands — full keyboard and command reference
• Thinking Steering — optimize token usage with intelligent thinking control