Commands
Kepler has three command surfaces: slash commands typed in the REPL, CLI flags passed when launching Kepler, and top-level subcommands for common tasks.
Slash Commands
Type these at the > prompt to control Kepler’s behavior. Commands are
grouped by function.
Worktree
| Command | Description |
|---|---|
/git, /status | Show git status |
/commit | Interactive git commit |
/diff | Show git diff |
/index | Build/rebuild BM25 context index for the project |
Session
| Command | Description |
|---|---|
/clear | Clear conversation history |
/sessions | List previous sessions |
/exit, /quit | Exit the Kepler REPL |
Usage
| Command | Description |
|---|---|
/model | Show the current active model |
/tokens | Show token usage for the current session |
/cost | Show session cost breakdown |
/cache | Show session cache hit-rate, cache_read / non-cached / total input tokens, cache_write. Numbers match provider dashboards (OpenRouter, Anthropic). |
/extra-usage | Detailed usage stats: tokens, cache read/write/hit-rate, telemetry event count |
Settings
| Command | Description |
|---|---|
/config | Open settings in the browser |
/login | Re-authenticate via browser |
/refresh | Reload credentials from disk |
/sync | Sync settings from the web dashboard |
/whoami | Show the currently logged-in user |
Built-in Agents
| Command | Description |
|---|---|
/explore <query> | Spawn a read-only code explorer agent |
/review <query> | Spawn a code review agent |
/architect <query> | Spawn an architecture planning agent |
Help
| Command | Description |
|---|---|
/help | Show available commands and basic usage |
/help <group> | Show commands for a specific group (worktree, session, usage, settings) |
Top-Level Subcommands
Run these directly from your terminal shell:
| Command | Description |
|---|---|
kepler | Start the interactive REPL |
kepler dashboard | Launch Kepler Pulse analytics dashboard |
kepler sessions | List recent local sessions |
kepler stats | Show aggregate local session statistics |
kepler history | Show recent prompt history |
kepler init | Scaffold .kepler/, including .kepler/KEPLER.md, settings, tasks, a starter skill, and a starter command |
kepler login | Sign in via browser (callback to bahulam.ai) |
kepler logout | Sign out and clear credentials |
kepler version | Show the installed version |
kepler help | Show help text |
Skills Subcommands
| Command | Description |
|---|---|
kepler skills list [--all|--project] | List installed skills |
kepler skills view <name> [resource] | View a skill’s details |
kepler skills install <path-or-git-url> | Install a skill from a path, GitHub URL, or npm package |
kepler skills update <name> | Update a skill |
kepler skills remove <name> | Remove a skill |
CLI Flags
Pass these when launching Kepler from the terminal.
| Flag | Description |
|---|---|
--model, -m <id> | Override the model for explicit-route headless or local runs |
--route, --model-route <platform|byok> | Explicit billing/credential route for backend headless --model |
--permission-mode <mode> | Set permission mode: bypassPermissions, acceptEdits, plan, auto, dontAsk |
--print, -p <prompt> | Non-interactive mode: run a single prompt and exit |
--output-format <fmt> | Output format: text (default), json, stream-json |
--system-prompt <text> | Override the system prompt |
--add-dir <dir> | Additional directory to search for CLAUDE.md |
--max-turns <n> | Maximum conversation turns before stopping |
--timeout <n> | Timeout in seconds |
--allowedTools <tools> | Comma-separated list of allowed tools |
--disallowedTools <tools> | Comma-separated list of denied tools |
--resume, --continue, -r [sessionId] | Resume the last session (or a specific session) |
--headless | Non-interactive mode: auto-approve, JSONL output to stdout |
--cache-report <file> | Write prompt-cache summary JSON to a file (headless only) |
--local | Force local agent mode (bypass backend, direct LLM API) |
--freeswim-open-waters, --freeswim, --yes | Skip all approval prompts |
--verbose, -v | Verbose output |
--debug, -d | Debug mode |
--plan | Start in planning mode (read-only, block all writes) |
--no-index | Skip project indexing on startup |
--help, -h | Show help text and exit |
--version | Print the installed version and exit |
Examples:
# Non-interactive: run a single prompt
kepler -p "What is the entry point of this project?"
# Headless mode with a platform model override
kepler platform --headless --timeout 300 --model deepseek/deepseek-v4-flash "Fix the bug"
# Headless mode with a BYOK model override
kepler byok --headless --timeout 300 --model anthropic/claude-sonnet-4-6 "Fix the bug"
# Resume the last session
kepler --resume
# Skip all approvals (use with caution)
kepler --yes
# Force local mode with direct API key
kepler --local --model claude-sonnet-4-6Backend headless --model requires an explicit route. platform uses
Kepler-managed credentials and credit billing; byok uses your configured
provider key and records usage without platform model-credit deduction.
Interactive mode uses the model configured in Kepler settings. Use the dashboard
or /settings to inspect or change the interactive default.
Environment Variables
See Reference → Environment Variables for the full list.
Common ones:
| Variable | Purpose |
|---|---|
KEPLER_HOME | Override the Kepler config directory (default: ~/.kepler) |
KEPLER_TOKEN | Auth token for CI/CD pipelines |
KEPLER_PRODUCT | Product variant |
KEPLER_NO_PREFLIGHT | Skip onboarding diagnostic on startup (1 or true) |
ANTHROPIC_API_KEY / ANTHROPIC_MODEL | Direct Anthropic access + default model |
OPENAI_API_KEY / OPENAI_BASE_URL | Direct OpenAI access + endpoint override |
OPENROUTER_API_KEY | OpenRouter for BYOK |
GEMINI_API_KEY / GOOGLE_API_KEY | Google AI (Gemini) access |
DEBUG / MCP_DEBUG | Enable verbose logging |