CLI Guide

CLI Guide

The Iris CLI provides a powerful command-line interface for interacting with LLM providers, managing API keys, and automating AI workflows. It’s designed for rapid prototyping, prompt testing, and integration into shell scripts and CI/CD pipelines.

Installation

Install the CLI using Go:

go install github.com/petal-labs/iris/cli/cmd/iris@latest

Verify the installation:

iris version
# iris v0.11.0 (go1.22.0, darwin/arm64)

Tip

Ensure $GOPATH/bin (typically ~/go/bin) is in your PATH environment variable.

Shell Completion

Enable shell completion for a better experience:

Bash

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

Zsh

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

Fish

# Add to ~/.config/fish/config.fish
iris completion fish | source

Quick Start

1. Set up an API key

   export OPENAI_API_KEY=sk-...
   # Or use the secure keystore
   iris keys set openai

2. Send your first chat

   iris chat "What is the capital of France?"

3. Try streaming output

   iris chat --stream "Write a haiku about programming"

4. Switch providers

   iris chat --provider anthropic --model claude-3-5-sonnet-20241022 "Hello!"

Command Reference

iris chat

Send chat completions to any configured provider.

iris chat [flags] <prompt>

Flags

Flag	Short	Description	Default
--provider	-p	LLM provider to use	openai
--model	-m	Model name	Provider default
--system	-s	System prompt	None
--temperature	-t	Sampling temperature (0.0-2.0)	0.7
--max-tokens		Maximum tokens in response	Model default
--stream		Stream output in real-time	false
--json	-j	Output as JSON	false
--raw	-r	Output only the response text	false
--file	-f	Read prompt from file	None
--image	-i	Include image URL or path	None
--interactive		Start interactive chat session	false
--timeout		Request timeout	60s
--verbose	-v	Show request/response details	false

Examples

# Basic chat
iris chat "Explain recursion in simple terms"

# With specific model
iris chat -p anthropic -m claude-3-opus "Write a sonnet"

# With system prompt
iris chat -s "You are a pirate" "What's the weather like?"

# Lower temperature for deterministic output
iris chat -t 0.1 "List the planets in order"

# Streaming for long responses
iris chat --stream "Write a short story about a robot"

# JSON output for scripting
iris chat --json "Summarize this text" | jq '.output'

# Read prompt from file
iris chat -f prompt.txt

# With image (vision models)
iris chat -i "https://example.com/photo.jpg" "Describe this image"
iris chat -i ./local-image.png "What's in this picture?"

# Multiple images
iris chat -i image1.jpg -i image2.jpg "Compare these images"

# Verbose mode for debugging
iris chat -v "Hello" 2>&1 | head -20

iris keys

Manage encrypted API keys in the local keystore.

iris keys <subcommand> [args]

Subcommands

Subcommand	Description
set <provider>	Store a new API key
get <provider>	Retrieve a stored key (masked)
list	List all stored providers
remove <provider>	Delete a stored key
test <provider>	Test if the key is valid
export	Export keys (for backup)
import	Import keys from backup

Examples

# Store API keys (prompts for value)
iris keys set openai
iris keys set anthropic
iris keys set gemini

# List stored keys
iris keys list
# openai
# anthropic
# gemini

# Test a key works
iris keys test openai
# ✓ OpenAI key is valid (organization: org-xxx)

# Remove a key
iris keys remove gemini

# Export for backup (encrypted)
iris keys export > keys-backup.enc

# Import from backup
iris keys import < keys-backup.enc

Caution

The keystore uses AES-256-GCM encryption. Set IRIS_KEYSTORE_KEY environment variable for non-interactive access, or the CLI will prompt for your master password.

iris models

List and inspect available models.

iris models <subcommand> [args]

Subcommands

Subcommand	Description
list [provider]	List available models
info <model>	Show model details
default [provider]	Show or set default model

Examples

# List all models for a provider
iris models list openai
# gpt-4o
# gpt-4o-mini
# gpt-4-turbo
# gpt-3.5-turbo
# text-embedding-3-small
# text-embedding-3-large
# ...

# List models for all providers
iris models list

# Get detailed info about a model
iris models info gpt-4o
# Name:        gpt-4o
# Provider:    openai
# Context:     128000 tokens
# Max Output:  16384 tokens
# Features:    chat, streaming, tools, vision, json_mode
# Pricing:     $5.00/1M input, $15.00/1M output

# Show default model
iris models default openai
# gpt-4o

# Set default model
iris models default openai gpt-4o-mini

iris embed

Generate embeddings for text.

iris embed [flags] <text>

Flags

Flag	Short	Description	Default
--provider	-p	Embedding provider	openai
--model	-m	Embedding model	Provider default
--dimensions	-d	Output dimensions	Model default
--file	-f	Read texts from file (one per line)	None
--output	-o	Output file (JSON)	stdout

Examples

# Generate embedding for text
iris embed "The quick brown fox"

# With specific model
iris embed -m text-embedding-3-large "Hello world"

# Reduce dimensions
iris embed -d 512 "Search query"

# Batch from file
iris embed -f documents.txt -o embeddings.json

# Pipe to other tools
iris embed "query text" | jq '.embedding[:5]'

iris init

Scaffold new Iris projects.

iris init [flags] <project-name>

Flags

Flag	Description	Default
--template	Project template	basic
--provider	Default provider	openai
--no-git	Skip git initialization	false

Templates

Template	Description
basic	Simple chat application
agent	Tool-using agent scaffold
rag	RAG pipeline with embeddings
api	HTTP API server

Examples

# Create basic project
iris init myproject

# Create agent project
iris init --template agent my-agent

# Create RAG project with Anthropic
iris init --template rag --provider anthropic my-rag-app

# Skip git
iris init --no-git quick-test

iris config

Manage CLI configuration.

iris config <subcommand> [args]

Subcommands

Subcommand	Description
show	Display current configuration
set <key> <value>	Set a configuration value
get <key>	Get a configuration value
edit	Open config file in editor
path	Show config file path

Examples

# Show all config
iris config show

# Set default provider
iris config set default_provider anthropic

# Set default model
iris config set default_model gpt-4o-mini

# Get a value
iris config get default_provider
# anthropic

# Edit config file
iris config edit

# Show config path
iris config path
# /Users/username/.iris/config.yaml

iris version

Display version and build information.

iris version [flags]

Flags

Flag	Description
--json	Output as JSON
--short	Version number only

Examples

iris version
# iris v0.11.0 (go1.22.0, darwin/arm64)
# Built: 2024-01-15T10:30:00Z
# Commit: abc123def

iris version --short
# v0.11.0

iris version --json
# {"version":"v0.11.0","go":"1.22.0","os":"darwin","arch":"arm64",...}

Configuration

Configuration File

The CLI reads configuration from ~/.iris/config.yaml:

# Default settings
default_provider: openai
default_model: gpt-4o

# Provider configurations
providers:
  openai:
    api_key_env: OPENAI_API_KEY
    default_model: gpt-4o
    organization: org-xxx  # Optional

  anthropic:
    api_key_env: ANTHROPIC_API_KEY
    default_model: claude-3-5-sonnet-20241022

  gemini:
    api_key_env: GEMINI_API_KEY
    default_model: gemini-1.5-pro

  ollama:
    base_url: http://localhost:11434
    default_model: llama3.2

# Chat defaults
chat:
  temperature: 0.7
  max_tokens: 4096
  stream: false

# Output preferences
output:
  color: true
  format: text  # text, json, markdown

# Telemetry
telemetry:
  enabled: false
  endpoint: ""

Environment Variables

Variable	Description
IRIS_KEYSTORE_KEY	Master password for encrypted keystore
IRIS_CONFIG	Custom config file path
IRIS_DEFAULT_PROVIDER	Override default provider
IRIS_DEFAULT_MODEL	Override default model
OPENAI_API_KEY	OpenAI API key
ANTHROPIC_API_KEY	Anthropic API key
GEMINI_API_KEY	Google Gemini API key
XAI_API_KEY	xAI (Grok) API key
PERPLEXITY_API_KEY	Perplexity API key
HUGGINGFACE_API_KEY	Hugging Face API key
VOYAGEAI_API_KEY	Voyage AI API key

Precedence Order

Configuration values are resolved in this order (highest priority first):

1. Command-line flags
2. Environment variables
3. Configuration file (~/.iris/config.yaml)
4. Built-in defaults

Interactive Mode

Start an interactive chat session for multi-turn conversations:

iris chat --interactive

Interactive Commands

Command	Description
/help	Show available commands
/clear	Clear conversation history
/system <prompt>	Set system prompt
/model <name>	Switch model
/provider <name>	Switch provider
/temperature <value>	Set temperature
/save <file>	Save conversation to file
/load <file>	Load conversation from file
/export	Export as JSON
/tokens	Show token usage
/quit or /exit	Exit interactive mode

Example Session

$ iris chat --interactive
Iris Interactive Mode (gpt-4o)
Type /help for commands, /quit to exit

You: Hello! What can you help me with?
Assistant: Hello! I'm Iris, your AI assistant. I can help you with:
- Answering questions and explaining concepts
- Writing and reviewing code
- Analyzing data and documents
- Creative writing and brainstorming

What would you like to explore?

You: /model gpt-4o-mini
Switched to model: gpt-4o-mini

You: What's 2+2?
Assistant: 2 + 2 = 4

You: /tokens
Session tokens: 127 (prompt: 89, completion: 38)

You: /save chat-history.json
Conversation saved to chat-history.json

You: /quit
Goodbye!

Scripting & Automation

The CLI is designed for integration into shell scripts and CI/CD pipelines.

JSON Output for Parsing

# Get structured output
result=$(iris chat --json "List 3 programming languages")
echo "$result" | jq '.output'

# Extract specific fields
tokens=$(iris chat --json "Hello" | jq '.usage.total_tokens')
echo "Used $tokens tokens"

Piping Input

# Pipe file content
cat README.md | iris chat "Summarize this document"

# Pipe command output
git diff | iris chat "Explain these changes"

# Chain commands
curl -s https://api.example.com/data | iris chat "Analyze this JSON"

Batch Processing

# Process multiple files
for file in docs/*.md; do
    echo "Processing $file..."
    iris chat -f "$file" --raw "Summarize this document" > "summaries/$(basename $file)"
done

# Parallel processing with xargs
find . -name "*.go" | xargs -P 4 -I {} sh -c 'iris chat -f {} --raw "Review this code" > {}.review'

Error Handling

#!/bin/bash
set -e

# Check if command succeeds
if iris chat --json "Hello" > /dev/null 2>&1; then
    echo "API is working"
else
    echo "API connection failed"
    exit 1
fi

# Capture errors
result=$(iris chat --json "Test" 2>&1) || {
    echo "Error: $result"
    exit 1
}

CI/CD Integration

# GitHub Actions example
- name: Generate Release Notes
  run: |
    git log --oneline v1.0.0..HEAD | \
      iris chat --raw "Generate release notes from these commits" > RELEASE_NOTES.md

# GitLab CI example
generate_docs:
  script:
    - iris chat -f src/main.go --raw "Generate API documentation" > docs/api.md

Environment-Specific Configuration

# Development
IRIS_DEFAULT_MODEL=gpt-4o-mini iris chat "Quick test"

# Production (use specific config)
IRIS_CONFIG=/etc/iris/prod.yaml iris chat "Generate report"

# Testing with local Ollama
iris chat -p ollama -m llama3.2 "Test local model"

Troubleshooting

Common Issues

”Command not found: iris”

Ensure Go bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin
# Add to ~/.bashrc or ~/.zshrc for persistence

“API key not found”

Check your key configuration:

# Check environment
echo $OPENAI_API_KEY

# Check keystore
iris keys list

# Test the key
iris keys test openai

“Model not found”

Verify the model name:

# List available models
iris models list openai

# Check model info
iris models info gpt-4o

Timeout Errors

Increase the timeout for long operations:

iris chat --timeout 120s "Write a long document..."

Rate Limiting

Add delays between requests in scripts:

for prompt in "${prompts[@]}"; do
    iris chat "$prompt"
    sleep 2  # Wait 2 seconds between requests
done

Debug Mode

Enable verbose output to diagnose issues:

# Show request/response details
iris chat -v "Hello"

# Show even more detail
IRIS_DEBUG=1 iris chat "Hello"

Log Files

Check logs for detailed error information:

# Default log location
cat ~/.iris/logs/iris.log

# Tail logs in real-time
tail -f ~/.iris/logs/iris.log

Next Steps

Streaming Guide

Advanced streaming patterns. Streaming →

Tools Guide

Build tool-augmented agents. Tools →

Providers

Configure different providers. Providers →

Examples

See complete working examples. Examples →