CLI Reference

Complete reference for the Claif command-line interface.

Installation

Install Claif using pip or uv:

# Using pip
pip install claif

# Using uv (recommended)
uv pip install claif

Basic Usage

claif [COMMAND] [OPTIONS] [ARGUMENTS]

Global Options

These options work with all commands:

Option	Short	Description	Default
--help	-h	Show help message
--verbose	-v	Enable verbose output	false
--debug		Enable debug logging	false
--config	-c	Path to config file	~/.claif/config.toml
--provider	-p	Default provider to use	From config

Commands

query

Send a query to an AI provider.

claif query "What is machine learning?" --provider claude

Syntax

claif query MESSAGE [OPTIONS]

Arguments

• MESSAGE - The message to send to the AI provider

Options

Option	Short	Type	Description	Default
--provider	-p	str	Provider to use (claude, gemini, codex)	From config
--temperature	-t	float	Sampling temperature (0.0-1.0)	0.7
--max-tokens	-m	int	Maximum tokens in response	1000
--timeout		float	Request timeout in seconds	120.0
--stream	-s	bool	Stream response in real-time	false
--format	-f	str	Output format (text, json, markdown)	text
--no-color		bool	Disable colored output	false
--save		str	Save response to file

Examples

# Basic query
claif query "Explain quantum computing"

# Use specific provider with options
claif query "Write a Python function" --provider claude --temperature 0.5

# Stream response
claif query "Tell me a story" --stream

# Save response to file
claif query "Code review best practices" --save response.md

# Output as JSON
claif query "List 5 programming languages" --format json

config

Manage Claif configuration.

claif config show
claif config set providers.claude.api_key sk-...

Subcommands

show

Display current configuration.

claif config show [--format FORMAT]

Options:

• --format - Output format (yaml, json, toml) [default: yaml]

Example:

claif config show --format json

set

Set a configuration value.

claif config set KEY VALUE

Arguments:

• KEY - Configuration key (dot notation supported)
• VALUE - Configuration value

Examples:

# Set default provider
claif config set default_provider claude

# Set API key
claif config set providers.claude.api_key sk-ant-...

# Set timeout
claif config set timeout 60.0

# Set provider-specific option
claif config set providers.gemini.model_name gemini-pro

get

Get a configuration value.

claif config get KEY

Arguments:

• KEY - Configuration key

Examples:

claif config get default_provider
claif config get providers.claude.api_key

unset

Remove a configuration value.

claif config unset KEY

Arguments:

• KEY - Configuration key to remove

edit

Open configuration file in default editor.

claif config edit

reset

Reset configuration to defaults.

claif config reset [--confirm]

Options:

• --confirm - Skip confirmation prompt

list

List available providers and their status.

claif list [OPTIONS]

Options

Option	Type	Description	Default
--format	str	Output format (table, json, yaml)	table
--available-only	bool	Show only available providers	false
--detailed	bool	Show detailed provider information	false

Examples

# List all providers
claif list

# Show only available providers
claif list --available-only

# Detailed information as JSON
claif list --detailed --format json

server

Start the MCP (Model Context Protocol) server.

claif server --port 8000

Options

Option	Type	Description	Default
--host	str	Host to bind to	localhost
--port	int	Port to bind to	8080
--workers	int	Number of worker processes	1
--reload	bool	Enable auto-reload for development	false

Examples

# Start server on default port
claif server

# Start on specific host and port
claif server --host 0.0.0.0 --port 8000

# Development mode with auto-reload
claif server --reload

install

Install provider CLI tools.

claif install claude

Syntax

claif install [PROVIDER] [OPTIONS]

Arguments

• PROVIDER - Provider to install (claude, gemini, codex, or ‘all’)

Options

Option	Type	Description	Default
--force	bool	Force reinstallation	false
--version	str	Specific version to install	latest
--dry-run	bool	Show what would be installed	false

Examples

# Install Claude CLI
claif install claude

# Install all providers
claif install all

# Force reinstall with specific version
claif install gemini --force --version 1.2.0

# Dry run to see what would be installed
claif install codex --dry-run

health

Check health status of providers and system.

claif health [OPTIONS]

Options

Option	Type	Description	Default
--provider	str	Check specific provider only
--format	str	Output format (table, json)	table
--timeout	float	Health check timeout	10.0

Examples

# Check all providers
claif health

# Check specific provider
claif health --provider claude

# Output as JSON
claif health --format json

version

Show version information.

claif version [OPTIONS]

Options

Option	Type	Description	Default
--format	str	Output format (text, json)	text

Configuration File

Claif uses a TOML configuration file located at ~/.claif/config.toml.

Example Configuration

# Default provider
default_provider = "claude"

# Global timeout
timeout = 120.0

# Default query options
[query_defaults]
temperature = 0.7
max_tokens = 1000
stream = false

# Provider configurations
[providers.claude]
api_key = "sk-ant-..."
model_name = "claude-3-sonnet-20240229"
timeout = 60.0

[providers.gemini]
api_key = "..."
model_name = "gemini-pro"
temperature = 0.8

[providers.codex]
api_key = "sk-..."
model_name = "gpt-4"
organization = "org-..."

# Logging configuration
[logging]
level = "INFO"
file = "~/.claif/logs/claif.log"
max_size = "10MB"
backup_count = 5

Configuration Keys

Global Settings

• default_provider (str) - Default provider to use
• timeout (float) - Default timeout in seconds
• log_level (str) - Logging level (DEBUG, INFO, WARNING, ERROR)

Query Defaults

• query_defaults.temperature (float) - Default temperature
• query_defaults.max_tokens (int) - Default max tokens
• query_defaults.stream (bool) - Default streaming behavior

Provider Settings

Each provider can have:

• api_key (str) - API key for the provider
• model_name (str) - Default model to use
• timeout (float) - Provider-specific timeout
• base_url (str) - Custom API base URL
• Custom provider-specific options

Environment Variables

Claif respects these environment variables:

Variable	Description	Default
CLAIF_CONFIG	Path to config file	~/.claif/config.toml
CLAIF_LOG_LEVEL	Logging level	INFO
CLAIF_DEFAULT_PROVIDER	Default provider	From config
CLAIF_TIMEOUT	Default timeout	120.0

Provider-Specific Variables

Claude

• ANTHROPIC_API_KEY - Claude API key
• CLAUDE_CLI_PATH - Path to Claude CLI executable

Gemini

• GOOGLE_API_KEY - Gemini API key
• GEMINI_CLI_PATH - Path to Gemini CLI executable

Codex

• OPENAI_API_KEY - OpenAI API key
• OPENAI_ORGANIZATION - OpenAI organization
• CODEX_CLI_PATH - Path to Codex CLI executable

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Provider error
4	Network/timeout error
5	Authentication error
130	Interrupted by user (Ctrl+C)

Shell Completion

Enable shell completion for better CLI experience:

Bash

# Add to ~/.bashrc
eval "$(claif --completion bash)"

Zsh

# Add to ~/.zshrc
eval "$(claif --completion zsh)"

Fish

# Add to ~/.config/fish/config.fish
claif --completion fish | source

Tips and Tricks

Aliases

Create useful aliases in your shell:

# Quick queries
alias ask="claif query"
alias claude="claif query --provider claude"
alias gemini="claif query --provider gemini"

# Streaming responses
alias stream="claif query --stream"

Piping and Redirection

# Pipe input
echo "Explain this code:" | cat - script.py | claif query

# Save to file
claif query "Write documentation" > docs.md

# Append to file
claif query "Add conclusion" >> docs.md

JSON Processing

Use jq for JSON output processing:

# Extract just the text response
claif query "Hello" --format json | jq -r '.content[0].text'

# Get multiple responses and format
claif query "List 3 colors" --format json | jq '.content[].text'

Configuration Management

# Backup current config
cp ~/.claif/config.toml ~/.claif/config.toml.backup

# Quick provider switching
claif config set default_provider claude
claif config set default_provider gemini

# Temporary config override
CLAIF_DEFAULT_PROVIDER=codex claif query "Code example"