CLI Backends Reference

Overview

Jean supports three CLI backends for AI interaction. This reference covers installation, authentication, configuration, and command-line usage for each.

Claude CLI

Installation

macOS (Homebrew):

brew install anthropics/claude/claude-cli

Manual download:

Visit the Claude CLI GitHub repository
Download the binary for your platform
Add to PATH

Verify installation:

claude --version

Authentication

# Interactive auth flow
claude auth

# Check auth status
claude auth status

# Logout
claude auth logout

API Key method:

export ANTHROPIC_API_KEY="sk-ant-..."

Configuration

Global settings: ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },
  "default_model": "claude-opus-4"
}

Project settings: .claude/settings.json in project root

{
  "env": {
    "PROJECT_SPECIFIC_VAR": "value"
  }
}

MCP servers: ~/.claude.json (global) or .mcp.json (project)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "disabled": false
    }
  }
}

Command-Line Usage

Basic chat:

claude "What is the capital of France?"

Model selection:

claude --model opus "Explain quantum computing"
claude --model sonnet "Write a Python script"
claude --model haiku "Quick question"

Thinking levels:

claude --thinking off "Simple query"
claude --thinking think "Moderate reasoning"
claude --thinking megathink "Complex problem"
claude --thinking ultrathink "Deep reasoning"

Effort levels (Opus 4.6):

claude --model opus --effort low "Quick task"
claude --model opus --effort high "Complex reasoning"
claude --model opus --effort max "No limits"

MCP config:

# Pass inline MCP config
claude --mcp-config '{"mcpServers":{"fs":{...}}}' "Query"

# Use project .mcp.json
claude --project-dir /path/to/project "Query"

JSON schema output:

claude --json-schema '{"type":"object","properties":{...}}' "Generate data"

Environment Variables

ANTHROPIC_API_KEY          # API key
ANTHROPIC_BASE_URL         # Custom endpoint (e.g., OpenRouter)
ANTHROPIC_AUTH_TOKEN       # Alternative auth token
ANTHROPIC_MODEL            # Default model
ANTHROPIC_DEFAULT_OPUS_MODEL      # Opus model ID
ANTHROPIC_DEFAULT_SONNET_MODEL    # Sonnet model ID
ANTHROPIC_DEFAULT_HAIKU_MODEL     # Haiku model ID
ANTHROPIC_SMALL_FAST_MODEL        # Fast model ID
API_TIMEOUT_MS             # Request timeout (ms)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC  # '1' to disable telemetry

Status Interface

interface ClaudeCliStatus {
  installed: boolean           // Whether CLI is installed
  version: string | null       // Installed version
  path: string | null          // Path to binary
  supports_auth_command: boolean  // Whether --auth is supported (v1.2+)
}

interface ClaudeAuthStatus {
  authenticated: boolean       // Whether authenticated
  error: string | null         // Error message if check failed
}

Codex CLI

Installation

Via installer (recommended):

Visit https://openai.com/codex
Download installer for your platform
Run installer

Via npm (if available):

npm install -g @openai/codex-cli

Verify installation:

codex --version

Authentication

# Interactive auth
codex auth

# Check status
codex auth status

# Logout
codex auth logout

API Key method:

export OPENAI_API_KEY="sk-..."

Configuration

Global config: ~/.codex/config.toml

[auth]
api_key = "sk-..."
base_url = "https://api.openai.com/v1"

[defaults]
model = "gpt-5.3-codex"
reasoning_effort = "high"

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

[mcp_servers.env]
FILESYSTEM_ROOT = "/allowed/path"

Project config: .codex/config.toml in project root

Command-Line Usage

Basic chat:

codex "Explain binary search"

Model selection:

codex --model gpt-5.3-codex "Complex task"
codex --model gpt-5.1-codex-mini "Quick query"

Reasoning effort:

codex --reasoning-effort low "Simple task"
codex --reasoning-effort medium "Moderate reasoning"
codex --reasoning-effort high "Complex problem"
codex --reasoning-effort xhigh "Deep reasoning"

Multi-agent mode (experimental):

codex --multi-agent --max-threads 5 "Complex project task"

MCP config:

codex --config /path/to/config.toml "Query"

Environment Variables

OPENAI_API_KEY             # API key
CODEX_BASE_URL             # Custom endpoint
CODEX_DEFAULT_MODEL        # Default model
CODEX_CONFIG_PATH          # Custom config path

Status Interface

interface CodexCliStatus {
  installed: boolean         // Whether CLI is installed
  version: string | null     // Installed version
  path: string | null        // Path to binary
}

interface CodexAuthStatus {
  authenticated: boolean     // Whether authenticated
  error: string | null       // Error message if check failed
}

OpenCode

Installation

Via npm:

npm install -g opencode

Via binary release:

Visit https://github.com/opencode/opencode/releases
Download for your platform
Add to PATH

Verify installation:

opencode --version

Authentication

OpenCode supports multiple providers: Anthropic:

opencode auth anthropic
# Enter API key when prompted

OpenAI:

opencode auth openai
# Enter API key when prompted

OpenRouter:

opencode auth openrouter
# Enter API key when prompted

Local models (Ollama):

# No auth needed
opencode config set provider ollama

Configuration

Global config: ~/.config/opencode/opencode.json

{
  "provider": "anthropic",
  "apiKey": "sk-ant-...",
  "model": "claude-opus-4",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "baseUrl": "https://api.anthropic.com"
    },
    "openai": {
      "apiKey": "sk-...",
      "baseUrl": "https://api.openai.com/v1"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434"
    }
  }
}

Project config: opencode.json in project root

Command-Line Usage

Basic chat:

opencode "Write a sorting algorithm"

Model selection:

# Anthropic via OpenCode
opencode --model opencode/anthropic/claude-opus-4 "Query"

# OpenAI via OpenCode
opencode --model opencode/openai/gpt-5 "Query"

# Local model via Ollama
opencode --model opencode/ollama/codellama "Query"

Provider override:

opencode --provider openrouter --model anthropic/claude-opus "Query"

MCP config:

opencode --config /path/to/opencode.json "Query"

Environment Variables

OPENCODE_API_KEY           # Default API key
OPENCODE_BASE_URL          # Default base URL
OPENCODE_PROVIDER          # Default provider
OPENCODE_MODEL             # Default model
OPENCODE_CONFIG_PATH       # Custom config path

Status Interface

interface OpencodeCliStatus {
  installed: boolean         // Whether CLI is installed
  version: string | null     // Installed version
  path: string | null        // Path to binary
}

interface OpencodeAuthStatus {
  authenticated: boolean     // Whether authenticated
  error: string | null       // Error message if check failed
}

Backend Detection

Jean detects backends by checking:

System PATH: which claude, which codex, which opencode
Common locations:
- macOS: /usr/local/bin/, /opt/homebrew/bin/
- Linux: /usr/bin/, /usr/local/bin/, ~/.local/bin/
- Windows: %ProgramFiles%, %LocalAppData%, %AppData%
Platform-specific:
- macOS: Checks Homebrew installation paths
- Windows: Checks registry keys
- Linux: Checks XDG directories

Version Requirements

Backend	Minimum Version	Recommended
Claude CLI	1.0.0	Latest stable
Codex CLI	0.5.0	Latest stable
OpenCode	0.1.0	Latest stable

Checking version:

claude --version
codex --version
opencode --version

Updating Backends

Claude CLI:

brew upgrade claude-cli

Codex CLI:

codex update
# Or re-run installer

OpenCode:

npm update -g opencode

Troubleshooting

Backend Not Detected

Verify installation: Run claude --version in terminal
Check PATH: echo $PATH (Unix) or echo %PATH% (Windows)
Reinstall via Jean UI: Preferences > Backends > Install
Restart Jean after installation

Authentication Fails

Run [backend] auth in terminal
Follow interactive prompts
Verify with [backend] auth status
Check API key is valid (not expired/revoked)
Restart Jean

Command Not Found

Error: /bin/sh: claude: command not found

Solution: Add CLI to PATH:

# ~/.zshrc or ~/.bashrc
export PATH="$PATH:/path/to/cli"

Permission Denied

Error: Permission denied: /usr/local/bin/claude

Solution:

chmod +x /usr/local/bin/claude

MCP Servers Not Loading

Check config file syntax (JSON/TOML)
Verify file location matches backend:
- Claude: .claude.json or .mcp.json
- Codex: config.toml
- OpenCode: opencode.json

Test MCP server manually:

npx -y @modelcontextprotocol/server-filesystem /path

Check logs: Help > Open Logs Folder

Jean-Specific Integration

Jean wraps CLI backends with additional functionality:

Features

Persistent sessions: Chat history saved across restarts
UI integration: Model/backend selection via dropdowns
Event streaming: Real-time message updates
Error handling: User-friendly error messages
Process management: Automatic cleanup on session close

Command Invocation

Jean constructs CLI commands based on session settings: Claude example:

claude \
  --model opus \
  --thinking ultrathink \
  --effort high \
  --project-dir /path/to/worktree \
  --mcp-config '{"mcpServers":{...}}' \
  --json-schema '{...}' \
  "User message"

Codex example:

codex \
  --model gpt-5.3-codex \
  --reasoning-effort high \
  --config /path/to/config.toml \
  --working-directory /path/to/worktree \
  "User message"

OpenCode example:

opencode \
  --model opencode/gpt-5.3-codex \
  --provider openrouter \
  --config /path/to/opencode.json \
  --working-directory /path/to/worktree \
  "User message"

Process Lifecycle

Spawn: Jean spawns CLI as child process
Stream: STDOUT streamed to UI in real-time
Parse: JSON stream parsed for structured output
Store: Messages saved to session database
Cleanup: Process killed on session close or cancel

Error Handling

interface CliError {
  code: number              // Exit code
  stderr: string            // Error output
  signal?: string           // Signal if killed
}

Common exit codes:

1 - General error
2 - Authentication failed
3 - API rate limit
130 - Process interrupted (Ctrl+C)

Custom Providers (Claude CLI)

Jean supports custom provider profiles for Claude CLI:

Profile Structure

interface CustomCliProfile {
  name: string                // Display name (e.g., "OpenRouter")
  settings_json: string       // JSON string with env block
  file_path?: string          // Path to saved settings file
  supports_thinking?: boolean // Whether provider supports thinking/effort
}

Example Profiles

See “Multi-Backend Setup” guide for predefined profiles (OpenRouter, MiniMax, Z.ai, Moonshot).

Creating Profiles

Preferences > Advanced > CLI Profiles
Add new profile
Configure environment variables
Save and select from provider dropdown

​Overview

​Claude CLI

​Installation

​Authentication

​Configuration

​Command-Line Usage

​Environment Variables

​Status Interface

​Codex CLI

​Installation

​Authentication

​Configuration

​Command-Line Usage

​Environment Variables

​Status Interface

​OpenCode

​Installation

​Authentication

​Configuration

​Command-Line Usage

​Environment Variables

​Status Interface

​Backend Detection

​Version Requirements

​Updating Backends

​Troubleshooting

​Backend Not Detected

​Authentication Fails

​Command Not Found

​Permission Denied

​MCP Servers Not Loading

​Jean-Specific Integration

​Features

​Command Invocation

​Process Lifecycle

​Error Handling

​Custom Providers (Claude CLI)

​Profile Structure

​Example Profiles

​Creating Profiles

Overview

Claude CLI

Installation

Authentication

Configuration

Command-Line Usage

Environment Variables

Status Interface

Codex CLI

Installation

Authentication

Configuration

Command-Line Usage

Environment Variables

Status Interface

OpenCode

Installation

Authentication

Configuration

Command-Line Usage

Environment Variables

Status Interface

Backend Detection

Version Requirements

Updating Backends

Troubleshooting

Backend Not Detected

Authentication Fails

Command Not Found

Permission Denied

MCP Servers Not Loading

Jean-Specific Integration

Features

Command Invocation

Process Lifecycle

Error Handling

Custom Providers (Claude CLI)

Profile Structure

Example Profiles

Creating Profiles