BeastCLI

AI-powered coding agent — runs GPT, Claude, Gemini, DeepSeek, and 200+ models in your terminal.

---

Install

npm install -g @simpletoolsindia/beastcli
beastcli --version    # verify installation

Requires Node.js 20+.

---

Quick Start

# Start interactive setup (auto-detects your provider)
beastcli

# Or set up via environment variables
OPENAI_API_KEY=sk-... beastcli -p "write a hello world in python"

---

Provider Setup

BeastCLI works with any OpenAI-compatible API. Set one of these:

Ollama (Free & Local)

# Install: https://ollama.ai
ollama pull qwen2.5-coder:7b

beastcli -p "write hello world" \
  --provider ollama \
  --bare

Or with environment variables:

BEASTCLI_PROVIDER=ollama \
OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_MODEL=qwen2.5-coder:7b \
beastcli -p "write hello world" --bare

OpenRouter (200+ Models)

Get a key at openrouter.ai/keys, then:

OPENAI_API_KEY=sk-or-v1-... \
OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
OPENAI_MODEL=google/gemma-3-4b-it \
beastcli -p "write hello world" --bare

Free models on OpenRouter: google/gemma-3-4b-it, deepseek/deepseek-chat-v3-0324:free, qwen/qwen-2.5-72b-instruct:free

NVIDIA NIM (GPU Accelerated)

Get a key at ngc.nvidia.com, then:

OPENAI_API_KEY=nvapi-... \
OPENAI_BASE_URL=https://integrate.api.nvidia.com/v1 \
OPENAI_MODEL=google/gemma-3-4b-it \
beastcli -p "write hello world" --bare

OpenAI / Anthropic / Gemini

# OpenAI
OPENAI_API_KEY=sk-... beastcli -p "write hello world" --bare

# Anthropic
ANTHROPIC_API_KEY=sk-ant-... beastcli -p "write hello world" --bare

# Gemini (OpenAI-compatible endpoint)
GOOGLE_API_KEY=... \
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai \
OPENAI_MODEL=gemini-2.0-flash \
beastcli -p "write hello world" --bare

---

All Providers

Provider	Base URL	API Key Env Var
Ollama	http://localhost:11434/v1	None
OpenRouter	https://openrouter.ai/api/v1	OPENAI_API_KEY
NVIDIA NIM	https://integrate.api.nvidia.com/v1	OPENAI_API_KEY
OpenAI	https://api.openai.com/v1	OPENAI_API_KEY
Anthropic	(default)	ANTHROPIC_API_KEY
DeepSeek	https://api.deepseek.com/v1	OPENAI_API_KEY
Groq	https://api.groq.com/openai/v1	OPENAI_API_KEY
Together AI	https://api.together.xyz/v1	OPENAI_API_KEY
LM Studio	http://localhost:1234/v1	None
Custom	Any OpenAI-compatible	OPENAI_API_KEY

---

CLI Usage

Interactive Mode

beastcli                      # full interactive REPL
beastcli --provider ollama    # specify provider at startup
beastcli --model llama3.2     # specify model

Non-Interactive Mode (-p)

beastcli -p "write hello world in python"     # single prompt, print output
beastcli -p "explain this: $(cat file.py)"     # pipe input
echo "fix this bug" | beastcli -p              # stdin input
beastcli -p --model gpt-4o "analyze this code" # specify model

Scripting / CI Mode (--bare)

# Minimal mode: skips UI, auth, plugins — for scripts and CI
beastcli -p "write tests" --bare

# Chain prompts
beastcli -p "plan the feature" --bare > plan.txt
beastcli -p "implement based on plan" --bare

---

Built-in Tools (No API Key Required)

These run locally without any API key:

Tool	Example	Description
Calculator	/calc 2+2	Math operations
UUID	/uuid	UUID v1/v4/v7
Hash	/hash sha256 "text"	MD5, SHA, etc.
Base64	/base64 encode "hi"	Encode/decode
JSON	/json format '{}'	Format/validate
QR Code	/qr "https://..."	Generate QR
Color	/color #FF0000	HEX/RGB/HSL
URL	/url parse "..."	Parse/encode URLs
Regex	/regex "[a-z]+" "abc"	Test regex
Password	/password 16	Secure passwords
Text Diff	/diff "a" "b"	Compare text
Text Stats	/stats "text"	Word count, etc.
Lorem	/lorem 5	Placeholder text
Cron	/cron "0 9 * * *"	Parse cron
Timezone	/tz Tokyo	Time zones
Currency	/currency 100 USD EUR	Conversion
IP Lookup	/ip 8.8.8.8	Geolocation
Weather	/weather Tokyo	Current weather
News	/news tech	Tech news
Timestamp	/timestamp	Unix time
YouTube	/transcript "url"	Video transcripts

---

Slash Commands

Command	Description
/help	Show help
/clear	Clear chat
/config	Open settings UI
/provider	Manage providers
/doctor	Run diagnostics
/commit	Git commit wizard
/diff	Show changes
/plan	Structured planning
/task	Task management
/agent	Spawn sub-agent
/compact	Compact context
/mcp add	Add MCP server
/skills	List/install skills

---

Keyboard Shortcuts

Key	Action
Ctrl+C	Cancel operation
Ctrl+D	Exit BeastCLI
Tab	Autocomplete
↑/↓	Command history
Ctrl+L	Clear terminal

---

Configuration Files

Settings are stored at:

• macOS/Linux: ~/.beastcli/config.json
• Windows: %USERPROFILE%/.beastcli/config.json

To reset to defaults:

rm ~/.beastcli/config.json
beastcli    # fresh setup

---

Troubleshooting

"command not found" after install:

# Find where it was installed
which beastcli

# If using nvm, run:
npm install -g @simpletoolsindia/beastcli
hash -r

Ollama not connecting:

ollama serve            # ensure server is running
curl http://localhost:11434  # should return version

Rate limited (NVIDIA/OpenAI):

• Wait 60 seconds and retry
• Use a local model (Ollama) to avoid limits

Context too long:

/compact    # compact conversation context

---

Develop

git clone https://github.com/simpletoolsindia/beastcli
cd beastcli
npm install          # or: bun install
bun run build        # build dist/cli.mjs
bun test             # run test suite

Debug build errors:

bun run build 2>&1 | grep -i error

---

License

MIT — see LICENSE

---

Built by SimpleTools India
GitHub · NPM · Discord