CLI

Name: Gerbil
Author: Gerbil

The Gerbil CLI lets you run models, generate text, and manage everything from your terminal, no code required to get started.

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.5-0.8b --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.5-0.8b
`-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

Model switching, thinking mode, and tool calling are all available inside the REPL, press Esc for the menu.

Text-to-Speech

Generate speech on-device with native Kani-TTS-2:

Terminal

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

# Adjust speech speed (0.5-2.0)
gerbil speak --speed 1.2 "Cheerio!"

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

# Pick a different TTS model
gerbil speak --model OuteAI/OuteTTS-1.0-0.6B "Hello world"

# List TTS models and voices
gerbil speak --list-models
gerbil speak --list-voices

Speech-to-Text

Transcribe audio files on-device with native Moonshine:

Terminal

# Transcribe audio file
gerbil transcribe recording.wav

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

# Show timestamps for each segment
gerbil transcribe recording.wav --timestamps

# List STT 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 the LLM and STT models
gerbil voice question.wav --model qwen3.5-0.8b --stt-model whisper-tiny.en

# 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 (Moonshine), generates a response (LLM), and speaks it back (Kani-TTS-2).

Built-in Skills

Terminal

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

# Summarize a text file
gerbil summarize README.md
gerbil summarize notes.md --length short --format bullets

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

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

Model Management

Terminal

# List available models
gerbil models

# Search models
gerbil models --search "qwen"

Models download automatically the first time you use them and stay cached on disk. Use gerbil cache and gerbil cleanup to manage disk space.

Server Mode

Terminal

# Opens REPL Serve view (interactive)
gerbil serve

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

System Info

Terminal

# Opens REPL Info view (interactive)
gerbil info

# CLI mode (text output)
gerbil info --cli
gerbil info --cli --model qwen3.5-0.8b

# Benchmark a model
gerbil bench
gerbil bench --model qwen3.5-0.8b --runs 5

Cache Management

Terminal

# Show cached models and disk usage
gerbil cache

# Remove models older than 7 days
gerbil cache --older-than 7

# Remove all cached models
gerbil cache --clean

# Show what the cache is holding
gerbil cleanup

# Free the most space
gerbil cleanup --all

Structured Output

Generate validated JSON straight from the terminal:

Terminal

# Generate a JSON object
gerbil object "Extract the name and age: John is 25"

# Validate against required keys (JSON file with { "required": ["name", "age"] })
gerbil object --schema shape.json "Extract the name and age: John is 25"

# Retries and sampling
gerbil object --retries 2 --temperature 0.3 "List three colors as JSON"

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.

Manual Update Command

Dedicated command with clear progress feedback:

Terminal

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

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