CLI Reference

aspy provides a command-line interface for configuration management.

Basic Usage

# Run the proxy (normal operation)
aspy

# Run in demo mode (mock events for testing)
ASPY_DEMO=1 aspy

# Configuration management
aspy config [OPTIONS]

Configuration Commands

Interactive Setup

aspy config --init

Launches an interactive setup wizard that guides you through:

1. Theme selection - Choose from popular themes or view all 32 options
2. Proxy settings - Configure bind address
3. Features - Enable/disable storage, thinking panel, stats

The wizard creates ~/.config/aspy/config.toml with your choices.

Show Configuration

aspy config --show

Displays the effective configuration after merging:

1. Environment variables (highest priority)
2. Config file
3. Built-in defaults (lowest priority)

Example output:

# Effective configuration (env > file > defaults)

theme = "Spy Dark"
use_theme_background = true
context_limit = 147000
bind_addr = "127.0.0.1:8080"
log_dir = "./logs"

[features]
storage = true
thinking_panel = true
stats = true

[augmentation]
context_warning = true
context_warning_thresholds = [60, 80, 85, 90, 95]

# Source: /home/user/.config/aspy/config.toml

Edit Configuration

aspy config --edit

Opens the config file in your preferred editor (detected from $EDITOR or $VISUAL, falls back to nano on Unix, notepad on Windows).

If no config file exists, creates one with defaults first.

Update Configuration

aspy config --update

Merges new defaults into your existing config file while preserving your customizations. Useful after upgrading Aspy to get new configuration options.

Shows a colored diff preview before applying:

• Green lines = additions
• Red lines = removals

Creates a backup at config.toml.bak before making changes.

Reset Configuration

aspy config --reset

Overwrites the config file with defaults. Prompts for confirmation if the file exists.

Show Config Path

aspy config --path

Prints the config file path:

/home/user/.config/aspy/config.toml

Embeddings Commands

Manage the semantic search embedding system:

# Check indexer status (works with or without proxy running)
aspy embeddings --status

# Force reindex all content (clears existing embeddings)
aspy embeddings --reindex

Status Output

Offline mode (proxy not running):

Embeddings Status (Offline)
  Provider:   remote
  Model:      text-embedding-3-small
  Dimensions: 1536
  Total:      0/530 (0.0%)

Live mode (proxy running):

Embeddings Status (Live)
  Indexer:    RUNNING
  Provider:   remote
  Model:      text-embedding-3-small
  Progress:   127/530 (23.9%)

See Semantic Search Guide for full configuration.

Configuration File Format

Location: ~/.config/aspy/config.toml

# Theme (use 't' in TUI to see all options)
theme = "Spy Dark"
use_theme_background = true

# Layout preset: classic, reasoning, debug
preset = "classic"

# Context window limit for the gauge
context_limit = 147000

# Proxy bind address
bind_addr = "127.0.0.1:8080"

# Log directory for session files
log_dir = "./logs"

# Feature flags
[features]
storage = true          # Write events to JSONL files
thinking_panel = true   # Show Claude's extended thinking
stats = true            # Track tokens, costs, tool distribution

# Augmentation (response modifications)
[augmentation]
context_warning = true  # Inject usage alerts when context fills up
context_warning_thresholds = [60, 80, 85, 90, 95]

# Logging configuration
[logging]
level = "info"          # trace, debug, info, warn, error

# Multi-client routing (optional)
[clients.dev-1]
name = "Dev Laptop"
provider = "anthropic"

[providers.anthropic]
base_url = "https://api.anthropic.com"

Environment Variables

Environment variables override config file values:

Examples:

# Run with different bind address
ASPY_BIND=0.0.0.0:9090 aspy

# Run headless (no TUI, just proxy)
ASPY_NO_TUI=1 aspy

# Debug logging
RUST_LOG=debug aspy

# Demo mode with custom theme
ASPY_DEMO=1 ASPY_THEME="Spy Dark" aspy

Configuration Options Reference

General Options

Feature Flags

All features are enabled by default (opt-out pattern):

Augmentation

Logging

File logging example:

[logging]
level = "debug"
file_enabled = true
file_dir = "~/.local/share/aspy/logs"
file_rotation = "daily"
file_prefix = "aspy"

Creates files like aspy.2024-01-15.log in the specified directory.

Multi-Client Configuration

See docs/sessions.md for complete multi-client routing documentation.

[clients.<client-id>]
name = "Display Name"     # Required: human-readable name
provider = "provider-id"  # Required: references [providers.X]
tags = ["optional", "tags"]

[providers.<provider-id>]
base_url = "https://api.anthropic.com"  # Required: upstream API URL
name = "Optional Display Name"

Layout Presets

Version Information

aspy --version

Displays the current version number.