Skip to content

getting-started.md

Latest commit

 

History

History
160 lines (109 loc) · 4.4 KB

getting-started.md

File metadata and controls

160 lines (109 loc) · 4.4 KB

Getting Started

Requirements

  • Go 1.26 or later
  • Git (for extension installation)
  • An API key from at least one supported provider, or a local model server (LM Studio, Ollama, etc.)

Installation

Install piglet with a single command:

go install github.com/dotcommander/piglet/cmd/piglet@latest

Verify the installation:

piglet --version

Building from source: Clone the repository, then go build -o piglet ./cmd/piglet/ and move the binary to a directory on your $PATH.

API Keys

Piglet needs an API key from at least one LLM provider — or a local model server. Pick one:

Cloud Provider (API Key)

# Anthropic (recommended)
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google
export GOOGLE_API_KEY=AIza...

Add the export to your shell profile (~/.zshrc, ~/.bashrc, etc.) to make it permanent.

For other providers and advanced auth methods (secret managers, shell commands), see the Providers documentation.

Local Model (No API Key)

Start LM Studio, Ollama, or any OpenAI-compatible server, then point piglet at it:

piglet --model :1234          # LM Studio (default port)
piglet --model :11434         # Ollama (default port)
piglet --model :8080          # llama.cpp, MLX, vLLM

Piglet probes the server, discovers available models, and starts immediately. No API key, no account, no configuration file needed.

To auto-discover local servers on every startup, add them to ~/.config/piglet/config.yaml:

localServers:
  - http://localhost:1234

See Providers — Local Models for the full guide.

First Launch

Run piglet with no arguments to start the interactive TUI:

piglet

On the very first launch, piglet runs an automatic setup:

  1. Creates ~/.config/piglet/ with secure permissions
  2. Writes a model catalog (models.yaml) covering all supported providers
  3. Detects API keys from your environment
  4. Writes config.yaml with your default model
  5. Installs extensions in the background

You'll see output like this:

piglet — first-time setup

Creating ~/.config/piglet/...
  models.yaml ✓
Detected API keys: anthropic
  Default provider: anthropic (claude-opus-4-6)
  config.yaml ✓

Extensions will be installed automatically on first launch.

Setup complete! Run 'piglet' to start.

Run piglet again and the TUI appears immediately. Extensions build in the background while the UI loads — you can start typing right away.

Your First Conversation

Type a message and press Enter. Piglet streams the response in real time.

A few things to try:

> explain this codebase
> read main.go and suggest improvements
> find all TODO comments in this project

Piglet has built-in tools for reading files, writing code, running shell commands, and searching — the model calls them automatically when needed.

Useful Commands

Type /help to see all available commands. Here are the essentials:

Command Shortcut Description
/help List all commands
/model Ctrl+P Switch model
/session Ctrl+S Switch or create session
/clear Clear conversation history
/quit Ctrl+C Exit piglet

For the full command reference, see Commands.

One-Shot Mode

Pass a prompt as an argument to get a single response without entering the TUI:

piglet "what files are in this directory?"

Use --json for machine-readable output:

piglet --json "list the exported functions in main.go"

Next Steps

Topic Description
Configuration Customize settings, agent behavior, and tool limits
Providers Set up providers, configure auth, use local models
Extensions Install, manage, and disable extensions
Sessions Branching, forking, and conversation history
Commands All slash commands and keyboard shortcuts
Architecture How piglet works under the hood