loyal_companion/cli

Loyal Companion CLI

A quiet, terminal-based interface for conversations with Loyal Companion.

Installation

# Install dependencies
pip install typer httpx rich

# Make CLI executable
chmod +x lc

Quick Start

# Start the web server (required)
python3 run_web.py

# Start a conversation
./lc talk

Commands

lc talk

Start or resume a conversation.

lc talk                    # Resume default session
lc talk --new              # Start fresh default session
lc talk -s work            # Resume 'work' session
lc talk -s personal --new  # Start fresh 'personal' session

lc history

Show conversation history.

lc history               # Show default session history
lc history -s work       # Show 'work' session history
lc history -n 10         # Show last 10 messages

lc sessions

List or manage sessions.

lc sessions              # List all sessions
lc sessions -d work      # Delete 'work' session

lc config-cmd

Manage configuration.

lc config-cmd --show                           # Show current config
lc config-cmd --api-url http://localhost:8080  # Set API URL
lc config-cmd --email user@example.com         # Set email
lc config-cmd --reset                          # Reset to defaults

lc auth

Manage authentication.

lc auth           # Show auth status
lc auth --logout  # Clear stored token

lc health

Check API health.

lc health    # Check if API is reachable

Configuration

Configuration is stored in ~/.lc/config.json:

{
  "api_url": "http://127.0.0.1:8080",
  "auth_token": "web:user@example.com",
  "email": "user@example.com",
  "show_mood": true,
  "show_relationship": false
}

Sessions

Sessions are stored in ~/.lc/sessions.json:

• Multiple named sessions supported
• Sessions persist across CLI invocations
• Auto-save on exit

Design Philosophy

The CLI embodies the "empty table at closing time" philosophy:

• Quiet: No spinners, no ASCII art, minimal output
• Intentional: Explicit commands, named sessions
• Focused: Text-first, no distractions

Architecture

The CLI is a thin HTTP client that communicates with the Web API:

CLI (lc) → HTTP → Web API → ConversationGateway → Living AI Core

• Platform: CLI
• Intimacy: HIGH (via Web API)
• Transport: HTTP/REST

Development

Run component tests:

python3 test_cli.py

Dependencies

• typer>=0.9.0 - CLI framework
• httpx>=0.26.0 - HTTP client
• rich>=13.7.0 - Terminal formatting (optional)

Documentation

See Phase 4 Complete for full documentation.