PKS CLI

AI coding agent for your terminal — inspired by OpenCode.

Features

Core

• Multi-provider LLM support — OpenAI, Anthropic, Google, Azure, xAI, Groq, Mistral, Cohere, DeepSeek, OpenRouter, Together AI (11 providers)
• Tool system — Read, write, edit files, run shell commands, search code, fetch URLs, web search
• Dual agents — Build (full access) and Plan (read-only) modes
• Permission system — Tool approval flow with allow/deny/ask rules
• Session persistence — SQLite-backed conversation history
• Snapshot/revert — Undo file changes from tool execution
• MCP integration — Connect to Model Context Protocol servers
• Context sources — Auto-load AGENTS.md, README, package.json for project context
• Cost tracking — Real-time token usage and cost display

TUI (Interactive)

• Streaming responses — Real-time token output
• Tool call visualization — See which tools are being called and their results
• Model picker — Ctrl+M to switch between 20+ models
• Agent picker — Switch between Build/Plan agents
• Command palette — Ctrl+P for fuzzy command search
• Help panel — Ctrl+H for keyboard shortcuts
• Permission dialogs — Interactive approval for dangerous operations
• Status bar — Agent, model, tokens, cost, message count

CLI Commands

• pks — Launch interactive TUI
• pks run "prompt" — Non-interactive single prompt
• pks models — List all available models
• pks providers — Show provider status
• pks session list — List recent sessions
• pks session show <id> — View session details
• pks config show — Show configuration
• pks config set <key> <value> — Set config value
• pks config providers set <provider> <key> — Set API key
• pks agent build|plan — Switch agent type

Installation

cd pks-cli
npm install
npm run build
npm link  # makes 'pks' available globally

Configuration

Environment Variables

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_GENERATIVE_AI_API_KEY="..."
export AZURE_API_KEY="..."
export XAI_API_KEY="..."
export GROQ_API_KEY="..."
export MISTRAL_API_KEY="..."
export COHERE_API_KEY="..."
export DEEPSEEK_API_KEY="..."
export OPENROUTER_API_KEY="..."
export TOGETHER_API_KEY="..."

Config File

Create ~/.config/pks-cli/config.json:

{
  "model": "gpt-4o",
  "provider": "openai",
  "providers": {
    "openai": { "apiKey": "sk-..." },
    "anthropic": { "apiKey": "sk-ant-..." }
  },
  "permissions": [
    { "tool": "shell", "action": "ask" },
    { "tool": "write", "action": "allow", "pattern": "*.ts" }
  ],
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Project Config

Create .pks-cli.json in your project root:

{
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic"
}

TUI Keyboard Shortcuts

| Key | Action | |-----|--------| | Tab | Switch between Build/Plan agents | | Ctrl+P | Open command palette | | Ctrl+M | Open model picker | | Ctrl+N | New session | | Ctrl+L | Clear history | | Ctrl+Z | Revert last file changes | | Ctrl+H | Toggle help panel | | Ctrl+C | Exit | | Escape | Cancel current dialog |

Slash Commands

| Command | Action | |---------|--------| | /help | Show help panel | | /clear | Clear history | | /new | New session | | /model | Model picker | | /agent | Agent picker | | /build | Switch to build agent | | /plan | Switch to plan agent | | /revert | Revert last changes | | /quit | Exit |

Supported Providers

| Provider | Env Key | Models | |----------|---------|--------| | OpenAI | OPENAI_API_KEY | gpt-4o, gpt-4.1, o3, o4-mini | | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4, claude-opus-4 | | Google | GOOGLE_GENERATIVE_AI_API_KEY | gemini-2.5-pro, gemini-2.5-flash | | Azure | AZURE_API_KEY | gpt-4o, gpt-4o-mini | | xAI | XAI_API_KEY | grok-3, grok-3-mini | | Groq | GROQ_API_KEY | llama-3.3-70b, mixtral-8x7b | | Mistral | MISTRAL_API_KEY | mistral-large, codestral | | Cohere | COHERE_API_KEY | command-r-plus, command-r | | DeepSeek | DEEPSEEK_API_KEY | deepseek-chat, deepseek-coder | | OpenRouter | OPENROUTER_API_KEY | Multi-provider routing | | Together | TOGETHER_API_KEY | Llama, DeepSeek, etc. |

Tools

| Tool | Description | |------|-------------| | read | Read file contents with line numbers | | write | Create or overwrite files | | edit | Search and replace in files | | glob | Find files by pattern | | grep | Search file contents with regex | | shell | Execute shell commands | | webfetch | Fetch URL content | | websearch | Search the web | | list_dir | List directory contents | | question | Ask user for input |

License

MIT