CLI Reference

Invocation

# Via bun script
bun run cli <command> [subcommand] [args] [--flags]

# As installed binary
melian <command> [subcommand] [args] [--flags]

All server-dependent commands connect to http://127.0.0.1:3000 by default. Override with --port <number>.

Quick Start

# First-time setup wizard
melian setup

# Start the server
melian start

# Interactive chat
melian chat

# One-shot question
melian ask "What's on my calendar today?"

# Server health
melian status

Commands

setup

Interactive first-time configuration wizard. Creates ~/.melian/ with config files.

melian setup

Prompts for: LLM endpoint URL, Qdrant URL, server port, your name and interests. Optionally configures email accounts and iMessage (macOS only). Creates config.yaml, mcp.json, and personality.yaml.

start / dev

melian start    # Production server
melian dev      # Watch mode with auto-reload

chat

Interactive REPL chat session. Streams responses from the server, displays tool calls inline.

melian chat

• Prompt: >
• Tool calls shown as [calling archival_memory_search...]
• Spirit shifts shown as ✦ spirit shifted
• Exit with Ctrl+C

ask

One-shot question, no REPL. Useful for scripting and piping.

melian ask "Summarize my unread emails"
melian ask "Turn off the garage lights"

memory

melian memory core              # Show all core memory sections
melian memory search <query>    # Search archival + recall memory

Search returns archival results with similarity scores and recall results with timestamps.

jobs

melian jobs list                              # List all jobs with status
melian jobs create --name "reminder" \
  --schedule "daily at 9am" \
  --prompt "Remind me to check email"         # Create a job
melian jobs log <name-or-id>                  # Show run history
melian jobs run <name-or-id>                  # Trigger immediately
melian jobs pause <name-or-id>                # Disable
melian jobs resume <name-or-id>               # Enable
melian jobs delete <name-or-id>               # Remove

email

melian email accounts                 # List accounts with connection status
melian email setup <account-name>     # Configure/test account (OAuth for Gmail)
melian email check                    # Check all accounts for new mail
melian email summary                  # Show important unread (importance >= 0.6)
melian email search <query>           # Search emails
melian email read <id>                # Display full email body
melian email drafts                   # List pending drafts
melian email drafts approve <id>      # Send a draft
melian email drafts discard <id>      # Delete a draft
melian email send --account personal \
  --to "[email protected]" \
  --subject "Hello" \
  --body "Message body"               # Send directly

imessage

macOS only. Requires a running server with iMessage enabled.

melian imessage status          # Watcher status, contacts, last message
melian imessage history [limit] # Recent messages (default: 20)
melian imessage last [limit]    # Recent agent responses (default: 1)
melian imessage send <message>  # Send test message

calendar

melian calendar today              # Today's events
melian calendar week               # This week, grouped by day
melian calendar drafts              # Pending event drafts
melian calendar drafts approve <id> # Create event from draft
melian calendar drafts reject <id>  # Discard draft
melian calendar sync                # Force sync from Google Calendar

analytics

melian analytics                                  # 24h summary (default)
melian analytics summary --window 7d              # Last 7 days
melian analytics summary --since 2026-04-01       # Since date
melian analytics tokens                           # Token usage by context
melian analytics tools                            # Tool call breakdown
melian analytics models                           # Per-model statistics
melian analytics jobs                             # Job execution metrics

Summary output includes: total requests, tokens in/out, average response time, error rate, top tools, model stats, breakdown by context (cli, web, imessage, cron).

mcp

melian mcp list              # List servers with status and tool counts
melian mcp tools             # List all tools from connected servers
melian mcp add [name]        # Interactive server configuration
melian mcp remove <name>     # Delete server config

mcp add prompts for transport type (stdio or http), command/URL, args, and environment variables. Saves to ~/.melian/mcp.json.

models

melian models

Lists available models from the LLM endpoint with per-model metrics: request count, average response time, tokens/second, success rate.

config

melian config edit       # Open ~/.melian/config.yaml in $EDITOR
melian config validate   # Validate YAML/JSON syntax of config files

validate checks config.yaml, mcp.json, and personality.yaml.

service

Install Melian as a system service that starts on login.

melian service install    # Install + start (launchd on macOS, systemd on Linux)
melian service uninstall  # Remove service
melian service start      # Start service
melian service stop       # Stop service
melian service restart    # Stop + start
melian service status     # Check if running (shows PID)

attention

melian attention list [limit]   # Show attention events (default: 20)
melian attention stats          # Counts by classification and source
melian attention seed           # Seed reference embeddings from seeds.yaml

attention list displays: timestamp, state, actor, classification (with source and confidence), and body snippet. Reads directly from the local SQLite database (no server required).

Global Flags

Server-Independent Commands

Most commands require a running server. These do not:

• setup creates config files
• config edit/validate operates on files directly
• service install/uninstall/start/stop/status manages the process
• mcp add/remove edits ~/.melian/mcp.json
• attention list/stats/seed reads local SQLite