watt-cli

Terminal-first interface for 20watt agents. Stateful AI that remembers, reasons, and acts—right from your command line.

Install

npm install -g @twentywatt/watt-cli

Or with Homebrew:

brew install twentywatt/tap/watt-cli

Quick Start

# Authenticate
watt login

# Start chatting
watt

# Single command
watt "Explain what a monad is"

# Pipe data
git log --oneline | watt "Summarize this week's commits"

Authentication

Desktop (OAuth)

watt login

Opens your browser for secure sign-in. Tokens are stored in your system keychain.

Headless / CI / SSH

watt login --api-key

Paste your API key from app.20watt.com/console/settings.

The CLI auto-detects remote environments (SSH, Docker, CI) and prompts for API key auth.

Usage

Interactive Mode

watt                           # Start chatting
watt --session abc123          # Resume a session

Single Commands

watt "Your question here"
watt --agent:sage "Analyze this"

Piping Data

Agents work as Unix pipeline citizens:

# Pipe stdin
cat error.log | watt "Find the root cause"

# Chain agents
git diff | \
  watt --agent:lex "Extract changes" | \
  watt --agent:sage "Analyze impact" | \
  watt --agent:orion "Suggest tests"

Output Formats

Force structured output for downstream tools:

watt --format json "List top issues"
watt --format csv "Extract metrics"
watt --format table "Show status"

Supported: json, jsonl, csv, table, yaml, md, text

Agent Management

watt --agents                    # List your agents
watt --agents --create           # Create new agent (interactive)
watt --agents:create --provider anthropic --model claude-sonnet-4-5-20250929
watt --agents --retire [id]      # Retire an agent

Using Specific Agents

watt --agent:sage "Deep analysis needed"
watt --agent:lex "Extract structured data"
watt --agent:orion "Take action on this"

Colonies (Saved Workflows)

Capture multi-step pipelines for reuse:

# Create from flags
watt colony capture daily-report \
  --pipeline "lex:Extract metrics as JSON" \
  --pipeline "sage:Analyze trends" \
  --pipeline "orion:Recommend actions" \
  --format md

# Or from a manifest file
watt colony put my-workflow --file workflow.yaml

# Run a colony
cat data.json | watt --colony:daily-report

# List/show/delete
watt colony list
watt colony show daily-report
watt colony delete daily-report

See docs/colonies.md for the full schema.

Automation

Agents run headless for cron, CI, and scripts:

# Cron job
0 9 * * * git log --since="24h" | watt --agent:sage "Summarize" > ~/standup.md

# CI pipeline
git diff main | watt "Review for security issues" --format json

# Scripts
#!/bin/bash
npm audit | watt --colony:security-check > report.md

See docs/workflows.md for patterns.

Account Info

watt --me                        # Show account details
watt --me:usage                  # Usage statistics
watt --me:agents                 # Agent breakdown
watt --providers                 # Available providers/models

Shell Completions

# Bash
watt completion bash > ~/.config/watt/completion.bash
echo 'source ~/.config/watt/completion.bash' >> ~/.bashrc

# Zsh
watt completion zsh > ~/.config/watt/completion.zsh
echo 'source ~/.config/watt/completion.zsh' >> ~/.zshrc

# Fish
watt completion fish > ~/.config/fish/completions/watt.fish

Environment Variables

WATT_BASE_URL          # API endpoint (default: https://api.20watt.com/api/v1)
WATT_CONFIG            # Config file path (default: ~/.watt/config.json)
WATT_ACCESS_TOKEN      # API key for headless auth

Interactive Mode

The TUI provides a rich interactive experience:

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+C | Clear input / double-tap to exit | | Ctrl+D | Exit immediately | | Ctrl+P | Pause/resume streaming | | Ctrl+E | Expand/collapse tool outputs | | Ctrl+L | Clear conversation | | Ctrl+O | Toggle thinking display | | ↑ / ↓ | Navigate history | | Tab | Accept autocomplete suggestion | | Escape | Cancel or clear input |

Slash Commands

Type / to see available commands:

/help              Show all commands
/shortcuts         Keyboard shortcuts
/agents:list       List active agents
/agents:create     Create new agent
/agents:default    Set default agent
/me                Account info
/me:usage          Usage statistics
/config:permissions View workspace permissions
/clear             Clear conversation
/exit              Exit

Multi-Agent Channels

Mention multiple agents to start a collaborative channel:

@sage @lex help me refactor this authentication module

Agents will collaborate, share notes, and build on each other's responses.

Tool Output

Tool executions display in a hierarchical format:

● Read(src/index.ts)
  └ 1186 lines

● Search(pattern: "async", path: "src/")
  └ Found 23 matches

Press Ctrl+E to expand/collapse tool outputs.

Hackable Runtime

Watt is designed to be hackable — a programmable AI runtime, not just a chat interface.

Shell Mode

Enter an interactive exploration environment:

watt shell

/agents                    # List agents
/agent sage notes          # See what sage has learned
/sessions                  # Recent sessions
/memory search "auth"      # Search memories
/vars                      # Your variables
/aliases                   # Your shortcuts

Variables

Store and reference values:

watt set PROJECT=myapp
watt "Analyze the $PROJECT codebase"

Aliases

Create shortcuts for frequent commands:

watt alias create standup "git log --since=24h | watt 'summarize'"
watt @standup

Composition Primitives

Build complex workflows from simple operations:

# Conditional routing
watt "analyze" | watt --if "error" -a sage "explain the errors"

# Fan-out to multiple agents
cat code.py | watt --fan-out "sage,lex,orion" "review this" --merge

# Process line by line
cat urls.txt | watt --each "fetch and summarize {}"

# Map/reduce
cat logs.txt | watt --map "extract errors" | watt --reduce "categorize"

Hooks

Automate at lifecycle events:

watt hook create on:cd --load ".watt-context"
watt hook create on:error --run "notify-send 'Watt error'"

Debugging

See what's happening:

watt --debug:memory "query"   # Show memory retrieval
watt --explain "analyze"      # Execution summary

See docs/guides/hackable-runtime.md for the full guide.

Documentation

• Hackable Runtime Guide — Variables, aliases, hooks, composition
• Shell Commands Reference — All shell mode commands
• Composition Reference — --if, --fan-out, --each, --map/--reduce
• Variables, Aliases, Hooks — State management reference
• Architecture Guide — Software architecture and component overview
• Workflows & Automation — Cron jobs, CI pipelines, scheduled agents
• Colonies — Saved multi-agent workflows
• Pipeline Guide — Mixing agents with Unix tools

License

Proprietary © 20watt