KALAI CLI

Terminal-first AI coding agent. KALAI CLI reuses the same Kalai Agent backend as the VS Code extension, so your wallet, history, and settings stay in one place.

Agent filesystem mutations require approval by default, including sub-agent edits. --readonly enforces read-only tools; --yolo bypasses approvals and allows commands to run with your operating system permissions. A workspace directory does not isolate shell commands, Python, Node, or Docker. See the repository's agent security guide for execution and billing boundaries. Provider-native search is currently unavailable; use URL fetching for external sources.

Installation

npm install -g @culustech/kalai-cli

Quick Start

# Create a new Kalai account (opens browser)
kalai register

# Log in with your Kalai account
kalai login

# Ask a one-shot question
kalai ask "Explain this codebase"

# Or use the shortcut
kalai "What does package.json do?"

# Run an autonomous agent task
kalai agent "Find all TODO comments and list them"

# Start an interactive chat session
kalai chat

# Check wallet balance
kalai wallet

# Generate AGENTS.md for the current project
kalai index

Commands

| Command | Description | |---------|-------------| | kalai register | Open the registration page in your browser | | kalai login | Log in with email and password | | kalai logout | Clear locally stored credentials | | kalai wallet | Show wallet balance | | kalai config list | Show all configuration | | kalai config get <key> | Get a config value | | kalai config set <key> <value> | Set a config value | | kalai ask "<prompt>" | Send a one-shot prompt | | kalai ask "<prompt>" --paste | Send a prompt with the clipboard image attached | | kalai agent "<task>" | Run an autonomous agent task | | kalai agent "<task>" --paste | Run an agent task with the clipboard image attached | | kalai agent "continue" | Resume the most recent agent session in this directory | | kalai agent --continue <sessionId> | Resume a specific saved agent session | | kalai agent --new "<task>" | Force a new session even if a recent one exists | | kalai chat | Start an interactive chat session | | kalai chat --paste | Start chat with the clipboard image attached to the first message | | kalai index | Generate AGENTS.md for the current project | | kalai subagents list | List running and completed sub-agent tasks | | kalai subagents show <id> | Show a sub-agent task result | | kalai subagents show <id> --full | Dump the full sub-agent transcript | | kalai subagents stop <id> | Stop a running background sub-agent | | kalai upgrade | Upgrade to the latest CLI version | | kalai --version | Show CLI version |

Agent Mode

The agent can read files, run terminal commands, execute Python/Node.js code, and fetch web pages. By default, mutating tools prompt for approval. For implementation requests, it prioritizes taking action and verifying the result over narrating a plan. Sub-agents, memory lookups, and todo tracking are used when they add value rather than for every task.

# Auto-approve all tool calls (use with caution)
kalai agent "Refactor all console.log to use a logger" --yolo

# Read-only mode
kalai agent "Summarize the project structure" --readonly

# Resume the most recent agent session in the current directory
kalai agent "continue"

# Resume a specific session
kalai agent --continue abc-123

# Force a new session
kalai agent --new "Add a dark mode toggle"

Agent sessions are persisted to ~/.kalai/agent-sessions/<id>.json, so you can resume after an interruption with kalai agent "continue".

Sub-agents

The agent can dispatch focused tasks to isolated sub-agents while it continues working.

# Delegate a read-only exploration task to an explorer sub-agent
kalai agent "Explore the src folder and summarize the architecture with an explorer sub-agent"

# List running and completed sub-agent tasks
kalai subagents list

# Show the result of a completed sub-agent task
kalai subagents show sub_abc123

# Dump the full transcript
kalai subagents show sub_abc123 --full

# Stop a running background sub-agent
kalai subagents stop sub_abc123

Built-in profiles:

• coder — read/write/execute/search (default)
• explorer — read-only reconnaissance
• planner — analysis and planning without writes or shell commands

Custom profiles can be added as JSON files in .kalai/profiles/*.json in the workspace or ~/.kalai/profiles/*.json.

Chat Mode

kalai chat starts a persistent REPL with slash commands:

| Command | Description | |---------|-------------| | /new | Start a new session | | /sessions | List saved sessions | | /resume <id> | Resume a session | | /model <name> | Switch active model | | /paste | Attach the clipboard image to the next message | | /index | Generate AGENTS.md | | /usage | Show session info | | /wallet | Show wallet balance | | /logout | Sign out | | /exit | Quit chat |

Configuration

Configuration is stored in ~/.kalai/config.json:

{
  "backend": {
    "baseUrl": "https://api.kalaiagent.site"
  },
  "frontend": {
    "baseUrl": "https://www.kalaiagent.site"
  },
  "model": {
    "maxTokens": 4096,
    "temperature": 0.7
  },
  "agentic": {
    "enabled": true,
    "maxIterations": 50,
    "maxExecutionTimeMs": 600000
  },
  "tools": {
    "terminal": { "enabled": true, "autoApprove": false },
    "codeExecution": { "enabled": true, "autoApprove": false },
    "webSearch": { "enabled": true }
  }
}

Add "name": "<model-id>" under model to override the backend's default model.

Override via environment variables:

• KALAI_BACKEND_URL
• KALAI_FRONTEND_URL
• KALAI_MODEL

Security

• Tokens are stored in the OS credential store when possible, otherwise in an encrypted file at ~/.kalai/credentials.json.
• File-system tools are sandboxed to the current working directory unless AGENT_ALLOW_OUTSIDE_WORKING_DIRECTORY=true is set.
• Terminal and code-execution tools prompt for approval before running unless --yolo is used.

Development

cd CLI/npmjs
npm install
npm run dev

License

MIT

Response summaries show your remaining wallet balance without displaying per-request costs.

Clipboard screenshots and image paths

Copy a screenshot, then use kalai ask "What is in this screenshot?" --paste, kalai agent "Implement this screen" --paste, or kalai chat --paste. The default kalai "Describe this" --paste command works too. Use --paste "C:\Pictures\screen.png" to attach a saved PNG, JPEG, GIF, or WebP instead of reading the clipboard. Put the prompt before --paste.

In interactive input (kalai, kalai ask, kalai agent with no prompt, or kalai chat), Ctrl+V attaches a clipboard screenshot when the terminal forwards that key. The saved temporary image path is displayed and the image is sent with this input. Finish multiline ask/agent input with Ctrl+D (or Ctrl+Z then Enter on Windows). Normal text paste remains controlled by the terminal.

Some terminals intercept Ctrl+V and do not forward image paste events. Use --paste for ask/agent/default commands, or /paste inside chat in that case. Chat also supports /paste "C:\Pictures\screen.png" and an initial prompt: kalai chat "What can you see?" --paste.

Kalai cannot change a shell command while you are typing it before Kalai starts; auto-inserting --paste at that point requires terminal or shell integration. Windows clipboard screenshots use PowerShell STA capture; macOS requires pngpaste, and Linux requires wl-paste (Wayland) or xclip (X11).

Inside chat, What can you see? --paste attaches the clipboard image to that message. Both kalai chat --paste "What can you see?" and kalai chat "What can you see?" --paste are supported.