CLI¶

The pegg binary is both the TUI launcher and a full command-line tool. Run pegg help or pegg <command> --help at any time.

Invocation behavior¶

Errors are printed to stderr as pegg: <error> and the process exits with code 1. Successful commands exit 0. Interactive prompts cancelled with Ctrl+C also exit 1.

pegg run¶

Run the orchestrator agent on a message, streaming its progress, tools, thinking, and responses live. Without a message (or with --chat) it starts an interactive chat in the same session.

pegg run "Explain the build system"
pegg run --provider openai --model gpt-4o "Review internal/agent"
pegg run --model smart-router "Fix the flaky tests"   # needs smart_router.enabled
pegg run --session 3f2b1c... "Continue where we left off"

Model resolution follows the rules in Providers & Models. When resuming a session without an explicit provider/model, the session's stored model is reused.

Output¶

Streaming output is plain text, with ANSI colors only when stdout is a terminal:

Running orchestrator (openai/gpt-4o)

> Explain the build system
tool [orchestrator] read(path=Makefile)
result [orchestrator] read: Path: Makefile | ...
The build is driven by a small Makefile...
• orchestrator finished (2 iterations, 1.2K tokens, $0.003100)

• Tool calls are shown as tool [agent] name(args...); results are truncated to 500 characters.
• --show-thinking prints the model's raw reasoning; otherwise a Thinking... spinner is shown on a TTY.
• --show-subagent prints subagent content instead of a Subagent <name> line.
• When the context is compacted mid-run, a line like ↻ Context compacted (sliding-window) — 30 messages, 8000 tokens is printed.

Chat mode¶

With --chat, or when the message is empty, run enters a line-based chat loop:

chat mode: type a message, exit/quit to end
> add a test for the parser
...

Exit words: exit, quit, /exit, /quit, bye.

Attachments¶

--file can be repeated. The MIME type is inferred from the extension — images (.png, .jpg, .jpeg, .gif, .webp) and audio (.mp3, .wav) are sent as attachments, PDFs and text files as files. See Adding Context.

Session selection¶

--select-session opens a paginated picker (10 per page) filtered to sessions from the current project directory, showing title, provider/model, and creation time.

pegg serve¶

Start a server: the HTTP REST API by default, or ACP with --acp.

pegg serve                          # HTTP API on 127.0.0.1:8080
pegg serve --port 9000 --host 0.0.0.0
pegg serve --acp                    # ACP over HTTP at /acp
pegg serve --acp --stdio            # ACP over stdin/stdout

See HTTP and ACP.

pegg login¶

Add or update a provider with an API key.

pegg login
pegg login --provider anthropic --api-key sk-ant-...

The provider's model list is fetched before the config is saved, so a login only succeeds when the credentials work.

pegg connect¶

Connect this machine's agent to a website backend so you can chat with it from a browser. Only a pairing token is needed — create one on the website under Agents → Connect a device. The full walkthrough lives in Connect.

pegg connect <token>     # first run: connect and remember the token
pegg connect             # every run after that

The relay endpoint is built into the app, so nothing but a token is needed; point a self-hosted website at connect.relay_url in ~/.peggco/pegg.json. The pairing token is stored there too, and is only ever displayed masked.

pegg providers¶

pegg providers add exposes every provider config field:

pegg providers add --name anthropic --api-key [**REDACTED**]
pegg providers add --driver openai --base-url http://localhost:11434/v1 --api-key ollama

Running it with any of --name, --driver, or --base-url skips all prompts. Models are fetched in the background after saving; a failed fetch does not block the add — run pegg providers refresh to retry. Registered names use built-in endpoints; --base-url/--driver only affect driver entries and custom names.

pegg models¶

List cached models.

pegg models
pegg models --provider deepseek

pegg doctor¶

Check provider connectivity and look for updates.

checking providers...
  openai OK (64 models)
  groq FAIL  llm: provider error: status 401
checking for updates...
  You are running the latest version

Each provider is queried with a fresh (uncached) model fetch. If a newer release exists, doctor asks Do you want to update? (y/N) and can install it.

pegg config¶

pegg config show

show prints the resolved configuration as pretty JSON with API keys masked. It is the only config subcommand.

pegg sessions¶

list flags:

pegg sessions list --all --search refactor
pegg sessions show 3f2b1c8e-...

See Sessions.

pegg logs¶

View application logs.

pegg logs --level ERROR
pegg logs --search "mcp" --size 100

With the SQLite logger (default) logs come from ~/.pegg/logs.db. With the console logger, only the current process's in-memory buffer is available.

pegg cache¶

pegg cache clear
pegg cache clear --provider openai

pegg files¶

Print system file paths and whether they exist:

config  exists   /home/user/.peggco/pegg.json
logs    exists   /home/user/.pegg/logs.db
cache   exists   /home/user/.pegg/cache.db
sessions exists  /home/user/.pegg/sessions.db
lsps    missing  /home/user/.pegg/lsps

pegg mcp¶

add flags: --global, --project, --name, --transport local|http, --command, --arg (repeatable), --env KEY=VALUE (repeatable), --url, --header KEY=VALUE (repeatable). See MCP.

pegg lsp¶

add flags: --global, --project, --name, --command, --arg (repeatable), --filetype (repeatable), --rootmarker (repeatable), --download URL, --env KEY=VALUE (repeatable). See LSP.

pegg tui¶

Launch the terminal UI explicitly. Equivalent to running pegg on a terminal.

pegg version¶

pegg version
# pegg version 0.1.0

pegg update¶

Check for a newer release and install it in place.

Current version: 0.1.0
Latest version: 0.2.0
Updating to version 0.2.0...
Successfully updated to version 0.2.0

Shell completion¶

Cobra provides completion scripts for bash, zsh, fish, and PowerShell:

pegg completion bash > /etc/bash_completion.d/pegg
pegg completion zsh > "${fpath[1]}/_pegg"
pegg completion fish > ~/.config/fish/completions/pegg.fish

Headless and scripting examples¶

# One-shot prompt, output to stdout
pegg run "List the public API of this package"

# Pipe context in
cat error.log | pegg "Explain the root cause"

# Run in CI with an explicit model and no interactive pickers
pegg run --provider openai --model gpt-4o-mini "Run the tests and fix failures"

# JSON-free plain text is emitted when stdout is not a terminal
OUTPUT="$(pegg run --provider groq --model llama-3.3-70b-versatile 'Summarize README.md')"

For structured output, use the HTTP API instead.