Skip to content

Latest commit

 

History

History
457 lines (329 loc) · 11.7 KB

cli-reference.md

File metadata and controls

457 lines (329 loc) · 11.7 KB

CLI Reference

Complete command-line interface reference for Cipher, covering all modes, options, and commands.

Basic Usage

Basic usage (terminal) 
# Interactive CLI mode
cipher

# One-shot command
cipher "Your prompt here"

# Server modes  
cipher --mode api        # REST API server
cipher --mode mcp        # MCP server  
cipher --mode ui         # Web UI server

Global Options

Core Options

Option Description Example
--mode <mode> Execution mode: cli, api, mcp, ui cipher --mode api
--agent <path> Custom configuration file path cipher --agent /path/to/config.yml
--new-session [id] Start with new session cipher --new-session project-alpha
--strict Strict MCP connections only cipher --mode mcp --strict
--help Show help information cipher --help
--version Show version information cipher --version

API Mode Options

Option Description Default Example
--port <number> API server port 3000 cipher --mode api --port 8080
--host <address> API server host localhost cipher --mode api --host 0.0.0.0
--cors Enable CORS false cipher --mode api --cors

MCP Mode Options

Option Description Default Example
--mcp-transport-type <type> Transport: stdio, sse, streamable-http stdio cipher --mode mcp --mcp-transport-type sse
--mcp-port <number> MCP server port (for sse/streamable-http) 3000 (sse), 3001 (http) cipher --mode mcp --mcp-transport-type sse --mcp-port 4000
--mcp-host <host> MCP server host (for sse/streamable-http) localhost cipher --mode mcp --mcp-host 0.0.0.0 --mcp-transport-type sse
--mcp-dns-rebinding-protection Enable DNS rebinding protection false cipher --mode mcp --mcp-transport-type sse --mcp-dns-rebinding-protection
--timeout <ms> Tool execution timeout 60000 cipher --mode mcp --timeout 120000

UI Mode Options

Option Description Default Example
--ui-port <number> Web UI port 3001 cipher --mode ui --ui-port 8080
--ui-host <address> Web UI host localhost cipher --mode ui --ui-host 0.0.0.0

Execution Modes

CLI Mode (Default)

Interactive command-line interface:

CLI mode examples 
# Start interactive mode
cipher

# Direct prompt execution
cipher "Add this to memory: CORS issues in Vite are usually solved by configuring the proxy"

# With custom config
cipher --agent ./my-config.yml "What do I know about authentication?"

Features:

  • Interactive chat interface
  • Session management
  • Memory integration
  • Tool access

API Mode

RESTful HTTP API server:

API mode examples 
# Basic API server
cipher --mode api

# Custom port and host
cipher --mode api --port 8080 --host 0.0.0.0 --cors

# With custom agent config
cipher --mode api --agent ./production-config.yml

API Endpoints:

  • POST /api/chat - Send messages
  • GET /api/sessions - List sessions
  • POST /api/sessions - Create session
  • GET /api/config - Get configuration

MCP Mode

Model Context Protocol server:

MCP mode examples 
# Standard MCP server (stdio transport - default)
cipher --mode mcp

# Explicit stdio transport
cipher --mode mcp --mcp-transport-type stdio

# SSE transport (HTTP server)
cipher --mode mcp --mcp-transport-type sse --mcp-port 3000

# Streamable-HTTP transport (HTTP server)
cipher --mode mcp --mcp-transport-type streamable-http --mcp-port 3001

# Strict mode (reject invalid connections)
cipher --mode mcp --strict

Transport Types:

  • stdio: Direct process communication (default).
  • sse: Server-Sent Events over HTTP. Endpoint: /sse.
  • streamable-http: HTTP request/response with streaming. Endpoint: /http.

Environment Variables for MCP:

MCP environment variables 
# MCP server behavior
export MCP_SERVER_MODE=aggregator  # or 'default'
export AGGREGATOR_CONFLICT_RESOLUTION=prefix  # 'first-wins', 'error'
export AGGREGATOR_TIMEOUT=60000

UI Mode

Web interface server:

UI mode examples 
# Start web UI
cipher --mode ui

# Custom port
cipher --mode ui --ui-port 8080

# Accessible from network
cipher --mode ui --ui-host 0.0.0.0 --ui-port 3001

Access: Open http://localhost:3001 in your browser

Interactive CLI Commands

When running in CLI mode, use these commands within the session:

Session Management

Command Description Example
/session list List all sessions /session list
/session new [id] Create new session /session new project-beta
/session switch <id> Switch to session /session switch default
/session delete <id> Delete session /session delete old-session
/session rename <old> <new> Rename session /session rename temp project-final

System Commands

Command Description Example
/config Show current configuration /config
/stats Show usage statistics /stats
/help Show help /help
/clear Clear screen /clear
/exit Exit Cipher /exit

Available CLI Commands (Actual Implementation)

Command Description Example
/help [command] Show help information /help session
/exit Exit the CLI session /exit
/clear Reset conversation history for current session /clear
/config Display current configuration /config
/stats Show system statistics and metrics /stats
/tools List all available tools /tools
/prompt Display current system prompt /prompt
/session <subcommand> Manage conversation sessions /session list

Session Management Subcommands

Subcommand Description Example
/session list List all sessions with status and activity /session list
/session new [name] Create new session (optional custom name) /session new project-alpha
/session switch <id> Switch to different session /session switch default
/session current Show current session info /session current
/session delete <id> Delete session (cannot delete active) /session delete old-session
/session delete all Delete all sessions except active /session delete all

Advanced Commands

Command Description Example
/prompt-stats Show system prompt performance statistics /prompt-stats --detailed
/prompt-providers <subcommand> Manage system prompt providers /prompt-providers list
/show-prompt Display system prompt with enhanced formatting /show-prompt --detailed

Configuration File

Specify custom configuration with --agent:

Using a custom configuration file 
cipher --agent /path/to/custom-config.yml

Default locations:

  1. ./memAgent/cipher.yml
  2. ~/.config/cipher/cipher.yml
  3. /etc/cipher/cipher.yml

Environment Variables

Set these in your .env file or environment:

Core Settings

Core environment variables 
# LLM Configuration
OPENAI_API_KEY=sk-your-key
ANTHROPIC_API_KEY=sk-ant-your-key

# Memory Settings  
USE_WORKSPACE_MEMORY=true
DISABLE_REFLECTION_MEMORY=true  # default: true

# Vector Store
VECTOR_STORE_TYPE=qdrant
VECTOR_STORE_URL=your-endpoint

# Chat History
CIPHER_PG_URL=postgresql://user:pass@host:5432/db

MCP-Specific Settings

MCP-specific environment variables 
# MCP server mode
MCP_SERVER_MODE=aggregator  # or 'default'
AGGREGATOR_CONFLICT_RESOLUTION=prefix
AGGREGATOR_TIMEOUT=60000

# Transport settings
MCP_TRANSPORT_TYPE=stdio     # stdio, sse, or streamable-http
MCP_PORT=3000               # HTTP server port for sse/streamable-http transports

Examples

Development Setup

Examples: Development setup 
# Start with in-memory storage for testing
VECTOR_STORE_TYPE=in-memory cipher

# Start API server for development
cipher --mode api --port 8080 --cors

# Test MCP integration
cipher --mode mcp

# Test MCP with SSE transport
cipher --mode mcp --mcp-transport-type sse --mcp-port 4000

# Test MCP with streamable-HTTP transport  
cipher --mode mcp --mcp-transport-type streamable-http --mcp-port 5000

Production Deployment

Examples: Production deployment 
# Production API server
cipher --mode api --port 3000 --host 0.0.0.0 --agent /etc/cipher/production.yml

# MCP server with custom timeout (stdio)
cipher --mode mcp --timeout 120000 --agent /etc/cipher/mcp-config.yml

# Production MCP server with SSE transport
cipher --mode mcp --mcp-transport-type sse --mcp-port 3000 --agent /etc/cipher/mcp-config.yml

# Production MCP server with streamable-HTTP transport
cipher --mode mcp --mcp-transport-type streamable-http --mcp-port 3001 --agent /etc/cipher/mcp-config.yml

# Web UI for team access
cipher --mode ui --ui-port 80 --ui-host 0.0.0.0

Team Collaboration

Examples: Team collaboration 
# Start workspace memory session
USE_WORKSPACE_MEMORY=true cipher --new-session team-project

# Switch between team sessions
cipher
> /session switch team-frontend
> /session switch team-backend

Memory Management

Examples: Memory management 
# Search specific memories
cipher "What do I know about React hooks?"

# Add structured knowledge
cipher "Remember: Next.js 13+ uses app directory structure with layout.tsx and page.tsx files"

# Memory statistics
cipher
> /memory stats
> /stats

Exit Codes

Code Meaning
0 Success
1 General error
2 Configuration error
3 Connection error
4 Authentication error
5 Permission error

Troubleshooting

Common Issues

Command not found:

Troubleshooting: Command not found 
# Install globally
npm install -g @byterover/cipher

# Or use npx
npx @byterover/cipher --help

Configuration errors:

Troubleshooting: Configuration errors 
# Check configuration
cipher --config

# Use verbose logging
DEBUG=cipher:* cipher --mode api

MCP connection issues:

Troubleshooting: MCP connection issues 
# Test MCP server with custom timeout
cipher --mode mcp --timeout 120000

# Test specific transport types
cipher --mode mcp --mcp-transport-type sse --mcp-port 3000
cipher --mode mcp --mcp-transport-type streamable-http --mcp-port 3001

# Check HTTP endpoints
# SSE (establish stream)
curl -N -H "Accept: text/event-stream" http://localhost:3000/sse
# Streamable-HTTP (client must send Accept headers)
curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"1","method":"ping","params":{}}' \
  http://localhost:3001/http

Related Documentation