CLI

Name: Gerbil
Author: Gerbil

Command-line interface for Gerbil.

Installation

One-off — no install required:

Terminal

npx @tryhamster/gerbil "Your prompt here"

Global install — use gerbil directly:

Terminal

npm install -g @tryhamster/gerbil

Examples below use gerbil (assumes global install). Use npx @tryhamster/gerbil if not installed.

Generate Text

The default command generates text from a prompt:

Terminal

# Basic usage
gerbil "Write a haiku about coding"

# With options
gerbil "Explain recursion" --model qwen3-0.6b --max-tokens 200

# With thinking mode
gerbil "What is 17 × 23?" --thinking

# Stream output
gerbil "Tell me a story" --stream

# Output as JSON
gerbil "Extract the name" --json

Options

Option	Description	Default
`-m, --model`	Model to use	qwen3-0.6b
`-n, --max-tokens`	Maximum tokens	256
`-t, --temperature`	Sampling temperature	0.7
`-s, --system`	System prompt	-
`--thinking`	Enable thinking mode	false
`--stream`	Stream output	false
`--json`	Output as JSON	false

REPL (Interactive Mode)

Launch the full interactive REPL with model management, chat, skills, and more:

Terminal

# Launch REPL
gerbil repl

# Or just
gerbil

See the REPL documentation for full details.

REPL View Shortcuts

Jump directly to any REPL view:

Terminal

gerbil chat       # Chat view
gerbil skills     # Skills view
gerbil tools      # Tools view
gerbil model      # Model view
gerbil integrate  # Frameworks view
gerbil benchmark  # Benchmark view
gerbil info       # Info view
gerbil serve      # Serve view

All REPL features are available—press Esc to access the main menu.

Interactive Chat

Opens the REPL directly in chat view:

Terminal

# Start chat (opens REPL in chat view)
gerbil chat

# With options
gerbil chat --model qwen3-0.6b --thinking
gerbil chat --system "You are a pirate"

# Agent mode with tool calling
gerbil chat --agent

Text-to-Speech

Generate speech with Kokoro or Supertonic:

Terminal

# Speak text with default voice
gerbil speak "Hello world"

# Specify voice and speed
gerbil speak --voice bf_emma --speed 1.2 "Cheerio!"

# Save to file instead of playing
gerbil speak --output hello.wav "Hello world"

# Use Supertonic model
gerbil speak --model supertonic-66m --voice F1 "Hello"

Speech-to-Text

Transcribe audio files with Whisper:

Terminal

# Transcribe audio file
gerbil transcribe recording.wav

# With timestamps
gerbil transcribe recording.wav --timestamps

# Save to file
gerbil transcribe recording.wav --output transcript.txt

# Use specific model
gerbil transcribe recording.wav --model whisper-base.en

# List available models
gerbil transcribe --list-models

Voice Chat

Complete voice conversation loop (STT → LLM → TTS):

Terminal

# Voice chat from audio file
gerbil voice question.wav

# Customize models and voice
gerbil voice question.wav --model qwen3-1.7b --voice bf_emma

# With custom system prompt
gerbil voice question.wav --system "You are a pirate!"

# Enable thinking mode
gerbil voice question.wav --thinking

This transcribes your audio (Whisper), generates a response (LLM), and speaks it back (Kokoro TTS).

Built-in Skills

Terminal

# Generate commit message from staged changes
gerbil commit
gerbil commit --type conventional

# Summarize a file
gerbil summarize README.md
gerbil summarize doc.pdf --length short

# Explain code
gerbil explain src/index.ts
gerbil explain src/utils.ts --level beginner

# Code review
gerbil review src/index.ts
gerbil review src/ --focus security,performance

Model Management

Terminal

# List available models
gerbil models

# List installed models
gerbil models --installed

# Search models
gerbil models --search "code"

# Download a model
gerbil pull qwen3-0.6b
gerbil pull hf:microsoft/Phi-3-mini

# Remove a model
gerbil rm smollm2-135m

Server Mode

Terminal

# Opens REPL Serve view (interactive)
gerbil serve

# CLI mode (non-interactive)
gerbil serve --http --port 3000 --model qwen3-0.6b
gerbil serve --mcp --model qwen3-0.6b

System Info

Terminal

# Opens REPL Info view (interactive)
gerbil info

# CLI mode (text output)
gerbil info --cli
gerbil info --cli --model qwen3-0.6b

# Session stats
gerbil stats

# Benchmark a model
gerbil bench
gerbil bench --model qwen3-0.6b

Cache Management

Terminal

# Show cache info
gerbil cache

# Show cache stats
gerbil cache stats

# Clean old cache entries
gerbil cache clean
gerbil cache clean --older-than 7d

# Clear all cache
gerbil cache clear

Pipes & Redirection

Gerbil works great with Unix pipes:

Terminal

# Pipe input
echo "Explain this" | gerbil
cat README.md | gerbil "Summarize this"

# Use with git
git diff --staged | gerbil "Write a commit message"

# Chain commands
cat error.log | gerbil "Explain this error" | tee explanation.txt

Configuration

Terminal

# View config
gerbil config

# Set defaults
gerbil config set model qwen3-0.6b
gerbil config set device gpu
gerbil config set cache.enabled true

# Get a value
gerbil config get model

# Reset to defaults
gerbil config reset

Updates

Gerbil checks for updates automatically but never installs without your permission.

REPL

Version shown in header. When update available, press u to update:

Terminal

Gerbil v1.0.0  ·  Update v1.0.1 → Press u

# Press 'u'
⬇ Updating...
✅ Updated! Restart to use v1.0.1

CLI

After commands, shows update notification if available:

Terminal

$ gerbil "Hello"
Hello! How can I help you today?

💡 Update available: v1.0.0 → v1.0.1
   Run 'gerbil update' to install

Manual Update Command

Dedicated command with clear progress feedback:

Terminal

$ gerbil update
✔ Checking for updates...
ℹ Update available: v1.0.0 → v1.0.1
⠋ Installing v1.0.1...
✔ ✅ Updated to v1.0.1

  Restart your terminal or run 'gerbil' to use the new version.

Why no auto-update?

✓ User control — never downloads without permission
✓ Non-disruptive — background check doesn't block workflow
✓ CI/CD safe — won't break automation with surprise updates
✓ Bandwidth friendly — only downloads when approved