🐉 Beast CLI

AI Coding Agent in Your Terminal

Ask questions, write code, search the web, and more — all from the command line. Works on Linux, macOS, and Windows with rich TUI support!

📚 Documentation

Full documentation at: https://simpletoolsindia.github.io/code-cli/

Includes:

• Installation guide
• All REPL commands
• Provider configuration
• Theme customization
• Engineering tools

✨ What is Beast CLI?

Beast CLI is an AI assistant in your terminal. Instead of opening a website or app, you can chat with AI directly from your command line.

Use it to:

• 💬 Ask coding questions
• 🔍 Search the web for information
• 📝 Write and edit code
• 🛠️ Run terminal commands
• 📚 Explain how code works
• 🔊 Speak summaries aloud with text-to-speech (TTS)

You can use:

• 🤖 Free AI models (like Ollama) — runs on YOUR computer
• 💳 ChatGPT Plus — use your existing $20/month subscription (NEW!)
• 💰 Paid AI APIs — OpenAI, Claude, Gemini, and more

🚀 Getting Started (Zero-Config — One Command!)

# One-line install (auto-installs Node.js & ffmpeg if needed)
curl -fsSL https://raw.githubusercontent.com/simpletoolsindia/code-cli/main/install.sh | bash

That's it! The installer handles everything automatically:

• ✅ Auto-installs Node.js if missing
• ✅ Auto-installs ffmpeg for audio playback
• ✅ Enables TTS (text-to-speech) by default
• ✅ Configures PATH automatically

Start Using Beast

# Recommended for beginners — uses ChatGPT Plus automatically!
beast --defaults

# Or just run with prompts:
beast

Beast will guide you through choosing an AI model.

⚡ Quick Install

# Zero-config installer (auto Node.js + ffmpeg + TTS)
curl -fsSL https://raw.githubusercontent.com/simpletoolsindia/code-cli/main/install.sh | bash

# If you already have Node.js
npm install -g @simpletoolsindia/beast-cli
bun add -g @simpletoolsindia/beast-cli

🪟 Windows Support

Beast CLI has full Windows support with multiple UI modes:

Windows UI Modes

| Mode | Command | Best For | |------|---------|----------| | Terminal TUI | beast --tui | ✅ Recommended for Windows - colors, spinners, history | | REPL | beast | Fast, ASCII-safe, universal compatibility |

Installation on Windows

# Option 1: PowerShell installer (recommended) - Run in PowerShell as Administrator
irm https://raw.githubusercontent.com/simpletoolsindia/code-cli/main/install.ps1 | iex

# Option 2: npm (requires Node.js already installed)
npm install -g @simpletoolsindia/beast-cli

Note: Run PowerShell as Administrator for system-wide installation, or use option 2 for user-local install.

Windows Terminal

For the best experience on Windows, use Windows Terminal (available in Microsoft Store):

• Full ANSI color support
• Better Unicode/emoji rendering
• Faster performance

Quick Start

# Start the REPL (auto-detects API keys)
beast

# Use specific provider and model
beast --provider ollama --model llama3.2
beast --provider anthropic --model claude-sonnet-4-20250514
beast --provider openai --model gpt-5.4     # Latest GPT-5
beast --provider openai --model o3          # o-series reasoning

🔧 Configuration

Environment Variables

export OPENAI_API_KEY=sk-...           # For GPT-5, o-series (get from platform.openai.com)
export ANTHROPIC_API_KEY=sk-ant-...    # For Claude
export GEMINI_API_KEY=...              # For Gemini
export GROQ_API_KEY=...                # For Groq
export DEEPSEEK_API_KEY=...            # For DeepSeek
export MISTRAL_API_KEY=...            # For Mistral

Config File

Create ~/.beast-cli.yml:

provider: openai
model: gpt-5.4
theme: catppuccin-mocha
temperature: 0.7
maxTokens: 16384
autoCompact: true

📟 Commands

| Command | Description | |---------|-------------| | beast | Start the REPL | | beast --help | Show help | | beast --version | Show version | | beast --compact | Force context compaction | | beast --theme <name> | Change theme |

REPL Commands

| Command | Description | |---------|-------------| | /help | Show help | | /tools | List available tools | | /clear | Clear conversation | | /compact | Compact context | | /theme | Change theme | | /exit | Exit CLI |

🧠 Engineering Intelligence Tools

12 specialized tools for code analysis:

| Tool | Description | |------|-------------| | engi_task_classify | Classify task type (bug, feature, etc.) | | engi_repo_scope_find | Find minimum relevant files | | engi_flow_summarize | Explain code implementation flow | | engi_bug_trace_compact | Trace likely bug causes | | engi_implementation_plan | Build implementation plan | | engi_poc_plan | Define minimum viable POC | | engi_impact_analyze | Estimate blast radius | | engi_test_select | Choose minimum test set | | engi_doc_context_build | Build docs context | | engi_doc_update_plan | Plan docs updates | | engi_memory_checkpoint | Save task state | | engi_memory_restore | Restore saved task |

🔊 Text-to-Speech (TTS)

Beast CLI can speak summaries aloud using Microsoft Edge TTS (free, high quality, 47 English voices).

REPL TTS Commands

| Command | Description | |---------|-------------| | /tts speak <text> | Speak text aloud | | /tts list | List available English voices | | /tts config | Show current TTS configuration | | /tts set <voice> | Change the default voice | | /tts on/off | Enable/disable auto-play |

Example

beast> /tts speak Hello! I'm Beast CLI, your AI coding assistant.

Available Voices

beast> /tts list
en-US-AriaNeural      # Neural voice (default) — best quality
en-US-GuyNeural       # Male neural voice
en-US-JennyNeural     # Female neural voice
en-GB-SoniaNeural     # British female
en-AU-NatashaNeural   # Australian female
# ... 47 total English voices

Install Audio Player

TTS requires ffmpeg for audio playback. The installer handles this automatically. To install manually:

# Linux
sudo apt-get install ffmpeg

# macOS
brew install ffmpeg

# Windows (with Chocolatey)
choco install ffmpeg -y

🎨 Themes

Available themes:

• catppuccin-mocha (default)
• catppuccin-frappe
• catppuccin-latte
• claude (warm editorial style)
• dracula
• nord
• tokyonight
• gruvbox
• monokai
• one-dark

beast --theme dracula

🌐 Supported Providers

| Provider | Models | |----------|--------| | ChatGPT Plus (OAuth) | GPT-5.2-codex, o3, o4-mini, GPT-5.1 — Free with Plus! | | OpenAI API | GPT-5.4, o3-pro, GPT-4.1, GPT-4o, Codex | | Anthropic | Claude Opus 4, Sonnet 4, Haiku 4 | | Google | Gemini 2.0, 2.5 | | Groq | Llama 4, QWQ-32b | | DeepSeek | DeepSeek Chat, Coder | | Mistral | Mistral Large, Codestral | | Ollama | Local models (llama3.2, mistral, etc.) | | LM Studio | Local models | | Jan | Local models | | OpenRouter | 75+ models via single API |

🔑 Using ChatGPT Plus/Pro with Beast CLI

Beast CLI supports two ways to use GPT-5 models:

Option A: ChatGPT Plus OAuth (Free with Plus subscription!) ✅

No API billing needed — use your existing ChatGPT Plus/Pro subscription:

beast
# Select provider: 3) ChatGPT Plus (CHT) — OAuth
beast --provider codex --model gpt-5.2-codex

First-time OAuth login:

beast
# When prompted, a browser window opens for ChatGPT login
# After login, tokens are saved automatically

Commands:

/login    # Re-authenticate ChatGPT Plus
/logout   # Clear ChatGPT authentication

Models available via ChatGPT Plus OAuth: GPT-5.2, GPT-5.2-codex, GPT-5.1-codex, GPT-5.1, o3, o4-mini, and more. See full list with /models after selecting ChatGPT Plus.

Option B: OpenAI API (Pay-as-you-go)

Use any OpenAI model with an API key from platform.openai.com:

export OPENAI_API_KEY=sk-...
beast --provider openai --model gpt-5.4

| Model | Best For | Pricing | |-------|----------|---------| | gpt-5.4 | General use, latest frontier | $1.25/M input | | gpt-5.4-pro | Maximum intelligence | $15/M input | | o3 | Complex reasoning, coding | $15/M input | | o3-pro | Advanced reasoning | $60/M input | | o4-mini | Fast reasoning | $3/M input | | gpt-4.1 | Smart non-reasoning | $2/M input | | gpt-5-codex | Code generation | $3/M input |

Which should I use?

| | ChatGPT Plus OAuth | OpenAI API | |---|---|---| | Cost | Free (with $20/mo Plus) | $1-5/month | | Auth | Browser OAuth login | API key | | Models | GPT-5.2, o3, Codex | All OpenAI models | | Best for | Daily CLI use | Full API access |

🛠️ Development

# Clone the repo
git clone https://github.com/simpletoolsindia/code-cli.git
cd code-cli

# Install dependencies
bun install

# Build
bun run build:bin

# Run
bun run src/index.ts

📄 License

MIT License - see LICENSE

🙏 Acknowledgments

• Catppuccin - Beautiful pastel theme
• Anthropic - Claude API
• OpenAI - GPT API
• Bubble Tea - TUI inspiration
• edge-tts-universal - Free Microsoft Edge TTS