CLI Reference#

What you’ll learn: Complete reference for all Osprey Framework CLI commands

Overview#

The Osprey Framework provides a unified CLI for all framework operations. All commands are accessed through the osprey command with subcommands for specific operations.

Quick Reference:

osprey                    # Launch interactive menu (NEW in v0.7.7)
osprey --version          # Show framework version
osprey --help             # Show available commands
osprey init PROJECT       # Create new project
osprey generate COMMAND   # Generate components (MCP capabilities, servers)
osprey deploy COMMAND     # Manage services
osprey chat               # Start interactive chat
osprey config             # Manage configuration
osprey tasks              # Browse AI assistant tasks (NEW)
osprey claude             # Manage Claude Code skills (NEW)

Interactive Mode#

The framework provides an interactive terminal UI (TUI) that automatically launches when you run osprey without any arguments:

osprey

The TUI is completely optional - all existing direct commands continue to work exactly as before. Use whichever approach fits your workflow:

Interactive mode: Great for exploration, learning, and infrequent tasks
Direct commands: Perfect for direct control without visual overhead, for experienced users

Context-Aware Menus#

The interactive menu automatically detects your context and adapts accordingly:

Outside a Project Directory:

When not in a project directory, the menu offers:

Select nearby project - If framework projects are detected in subdirectories, you can select one to navigate to
Create new project (interactive) - Guided project creation with template, provider, and model selection
Show init command syntax - View direct CLI commands for scripting
Show main help - Display all available commands
Exit - Close the interactive menu

Inside a Project Directory:

When inside a project directory (detected by presence of config.yml), the menu shows:

chat - Start CLI conversation interface
deploy - Manage containerized services (with subcommands for up, down, status, etc.)
health - Run comprehensive system health check
config - Display current project configuration
init - Create a new project (in a different location)
help - Show all available commands
exit - Close the interactive menu

The menu displays your current project name and configuration (provider/model) for easy reference.

Interactive Project Creation#

The interactive project creation flow guides you through all the necessary steps:

Project Name: Enter a name for your project
Template Selection: Choose from available templates with descriptions:
- minimal - Basic skeleton for custom development
- hello_world_weather - Simple weather agent example
- control_assistant - Production control system integration template
Provider Selection: Select your AI provider (Cborg, OpenAI, Anthropic, Google, Ollama, etc.)
Model Selection: Choose from provider-specific models
API Key Setup:
- Automatically detects API keys from your shell environment
- Prompts for secure input if keys are not detected
- Generates .env file with detected or entered keys

The interactive flow is equivalent to using framework init with appropriate flags, but with helpful guidance and validation at each step.

Disabling Interactive Mode#

If you prefer to only use direct commands, you can bypass the interactive menu by:

Running specific commands directly: framework chat, framework deploy up, etc.
Using framework --help to see available commands
The menu never interrupts existing scripts or automation

Global Options#

These options work with all osprey commands.

`--project` / `-p`#

The --project flag allows you to specify the project directory for commands that operate on existing projects (chat, deploy, health, config), enabling multi-project workflows and CI/CD automation from any directory.

osprey COMMAND --project /path/to/project

Project Resolution Priority:

When determining which project to use, the framework checks in this order:

``–project`` CLI flag (highest priority)
``FRAMEWORK_PROJECT`` environment variable
Current working directory (default)

Examples:

# Work with specific project from anywhere
osprey chat --project ~/projects/weather-agent
osprey deploy status --project ~/projects/turbine-monitor

# Use environment variable for a session
export OSPREY_PROJECT=~/projects/my-agent
osprey chat              # Uses ~/projects/my-agent
osprey deploy status     # Uses ~/projects/my-agent

# CLI flag overrides environment variable
export OSPREY_PROJECT=~/projects/agent1
osprey chat --project ~/projects/agent2  # Uses agent2, not agent1

Use Cases:

Multi-project development: Switch between projects without changing directories
CI/CD pipelines: Deploy or test specific projects from central scripts
Automation: Run health checks across multiple projects
Parallel workflows: Work with multiple projects simultaneously

Commands supporting ``–project``:

osprey chat --project PATH
osprey deploy COMMAND --project PATH
osprey health --project PATH
osprey config --project PATH

Note: The osprey init command does not use --project because it creates a new project. Use --output-dir instead to specify where the new project should be created.

`--version`#

Show framework version and exit.

osprey --version

Output:

Osprey Framework version 0.7.0

`--help`#

Show help message for any command.

osprey --help
osprey init --help
osprey deploy --help
osprey chat --help
osprey config --help

CLI Customization#

You can customize the CLI appearance through the cli section in your project’s config.yml.

Example - Custom colors:

cli:
  theme: "custom"
  custom_theme:
    primary: "#4A90E2"      # Brand blue
    success: "#7ED321"      # Success green
    accent: "#F5A623"       # Accent orange
    command: "#9013FE"      # Command purple
    path: "#50E3C2"         # Path teal
    info: "#BD10E0"         # Info magenta

Example - Custom banner:

cli:
  theme: "default"
  banner: |
    ╔════════════════════════════════════════╗
    ║      MY PROJECT NAME                   ║
    ╚════════════════════════════════════════╝

All menu items, prompts, and messages will use your custom colors and banner. The default theme is used if no cli section is present.

Commands#

osprey init#

Create a new project from a template.

Syntax#

osprey init [OPTIONS] PROJECT_NAME

Arguments#

PROJECT_NAME: Name of the project directory to create. Will be created in the current directory.

Options#

--template <name>

Template to use for project initialization. Available templates:

minimal - Basic skeleton for custom development
hello_world_weather - Simple weather agent (recommended for learning)
control_assistant - Production control system integration template

Default: minimal

--registry-style <style>

Registry implementation style:

compact - Use helper functions (5-10 lines, recommended)
explicit - Full registry implementation (verbose, for learning)

Default: compact

Examples#

Create minimal project:

osprey init my-agent

Create from hello_world_weather template:

osprey init weather-demo --template hello_world_weather

Create with explicit registry style:

osprey init my-agent --template minimal --registry-style explicit

Create advanced agent:

osprey init my-assistant --template control_assistant

Generated Structure#

The osprey init command creates a complete, self-contained project:

my-agent/
├── src/
│   └── my_agent/           # Application code
│       ├── __init__.py
│       ├── registry.py     # Component registration
│       ├── context_classes.py
│       └── capabilities/   # Agent capabilities
├── services/               # Container services
│   ├── jupyter/           # Development environment
│   ├── open-webui/        # Web interface
│   └── pipelines/         # Processing pipeline
├── config.yml             # Complete configuration
├── .env.example           # Environment template
└── README.md              # Project documentation

osprey generate#

Prototype Feature

This is a prototype feature under active development. The API and generated code structure may change in future releases.

Generate Osprey components from various sources, including MCP (Model Context Protocol) servers.

Subcommands#

osprey generate capability: Generate Osprey capability from MCP server
osprey generate mcp-server: Generate demo MCP server for testing

osprey generate capability#

Generate a complete Osprey capability from an MCP server with automatic ReAct agent integration, classifier/orchestrator guides, and context classes.

Syntax:

osprey generate capability --from-mcp <URL_OR_SIMULATED> --name <NAME> [OPTIONS]

Required Arguments:

--from-mcp <url>: MCP server URL (e.g., http://localhost:3001) or simulated for demo mode with weather tools
--name, -n <name>: Name for the generated capability (e.g., slack_mcp, weather_mcp)

Optional Arguments:

--server-name <name>: Human-readable server name (default: derived from capability name)
--output, -o <path>: Output file path (default: ./capabilities/<name>.py)
--provider <provider>: LLM provider override for guide generation (e.g., anthropic, openai, cborg)
--model <model_id>: Model ID override for guide generation (e.g., claude-sonnet-4-20250514, gpt-4o)
--quiet, -q: Reduce output verbosity

Examples:

Generate from simulated mode (no server needed):

osprey generate capability --from-mcp simulated --name weather_mcp

Generate from real MCP server:

osprey generate capability --from-mcp http://localhost:3001 --name slack_mcp

Custom output location:

osprey generate capability --from-mcp http://localhost:3001 \
    --name slack_mcp --output ./my_app/capabilities/slack.py

Override LLM provider/model:

osprey generate capability --from-mcp simulated --name weather_mcp \
    --provider anthropic --model claude-sonnet-4-20250514

See MCP Capability Generation for detailed guide.

osprey generate mcp-server#

Generate a demo MCP server for testing Osprey’s MCP capability generation. The server uses FastMCP for simple, Pythonic MCP server implementation with weather tools.

Syntax:

osprey generate mcp-server [OPTIONS]

Optional Arguments:

--name, -n <name>: Server name (default: demo_mcp)
--output, -o <path>: Output file path (default: ./<name>_server.py)
--port, -p <port>: Server port (default: 3001)

Included Tools:

The generated server includes three weather-related tools:

get_current_weather - Get current weather conditions for a location
get_forecast - Get weather forecast for upcoming days
get_weather_alerts - Get active weather alerts and warnings

Examples:

Generate weather demo server (default):

osprey generate mcp-server

Generate on custom port:

osprey generate mcp-server --port 3002

Custom output location:

osprey generate mcp-server --name my_server --output ./servers/mcp.py

Running the Generated Server:

# Install FastMCP
pip install fastmcp

# Run the server
python demo_mcp_server.py

Testing with Osprey:

# Generate capability from the running server
osprey generate capability --from-mcp http://localhost:3001 --name demo_mcp

See MCP Capability Generation for complete workflow.

osprey deploy#

Manage containerized services (Jupyter, OpenWebUI, Pipelines).

Syntax#

osprey deploy COMMAND [OPTIONS]

Global Options#

--project PATH / -p PATH

Project directory to use. If not specified, uses OSPREY_PROJECT environment variable or current directory.

This option works with all deploy subcommands (up, down, status, etc.).

Example:

osprey deploy status --project ~/projects/my-agent
osprey deploy up --project ~/projects/my-agent --detached

Commands#

up

Start services defined in config.yml.

Options:

--detached - Run services in background

--dev - Development mode: use local framework instead of PyPI

Examples:

osprey deploy up                    # Start in foreground
osprey deploy up --detached         # Start in background
osprey deploy up --dev              # Start with local framework
osprey deploy up --detached --dev   # Background with local framework

down

Stop all running services.

Example:

osprey deploy down

restart

Restart all services.

Example:

osprey deploy restart

status

Show status of deployed services.

Example:

osprey deploy status

clean

Stop services and remove containers and volumes.

Example:

osprey deploy clean

rebuild

Rebuild containers from scratch (useful after Dockerfile changes).

Options:

--detached - Run services in background after rebuild

--dev - Development mode: use local framework instead of PyPI

Examples:

osprey deploy rebuild                    # Rebuild and start
osprey deploy rebuild --detached         # Rebuild in background
osprey deploy rebuild --detached --dev   # Rebuild with local framework

Configuration#

Services are configured in config.yml under deployed_services:

project_name: "my-agent"  # Project identifier for container tracking

deployed_services:
  - osprey.jupyter        # Jupyter development environment
  - osprey.open-webui     # Web chat interface
  - osprey.pipelines      # Processing pipeline

Project Directory:

All osprey deploy commands must be run from a project directory (containing config.yml), or use the --project flag:

# Option 1: Run from project directory
cd my-project
osprey deploy up

# Option 2: Use --project flag
osprey deploy up --project ~/projects/my-project

# Option 3: Use interactive menu (auto-handles directories)
osprey

Workflow#

Development workflow:

# Start services in foreground to monitor logs
osprey deploy up

# When done, stop with Ctrl+C or:
osprey deploy down

Production workflow:

# Start services in background
osprey deploy up --detached

# Check status
osprey deploy status

# View logs with podman
podman logs <container_name>

# Stop when needed
osprey deploy down

Service Access#

Once deployed, services are available at:

OpenWebUI: http://localhost:8080
Jupyter (read-only): http://localhost:8088
Jupyter (write): http://localhost:8089
Pipelines: http://localhost:9099

osprey chat#

Start an interactive conversation interface with your agent.

Syntax#

osprey chat [OPTIONS]

Options#

--tui

Launch the Terminal User Interface (TUI) instead of the default CLI.

Experimental Feature (New in v0.10.0)

The TUI is an experimental feature available for testing. It provides a full-screen terminal experience with real-time streaming and visual step tracking.

Requirements: pip install osprey-framework[tui]

--project PATH / -p PATH

Project directory to use. If not specified, uses FRAMEWORK_PROJECT environment variable or current directory.

See Global Options for multi-project workflow details.

--config PATH / -c PATH

Path to configuration file.

Default: config.yml in project directory

Examples#

# Start CLI chat (default)
osprey chat

# Start TUI chat (experimental)
osprey chat --tui

# Start chat in specific project
osprey chat --project ~/projects/my-agent

# TUI with specific project
osprey chat --tui --project ~/projects/my-agent

# Use custom config
osprey chat --config my-config.yml

# Use environment variable for project
export OSPREY_PROJECT=~/projects/my-agent
osprey chat

Terminal User Interface (TUI)#

Experimental Feature (New in v0.10.0)

The TUI is experimental and available for testing. Feedback welcome!

The TUI provides a full-screen terminal experience built with Textual:

Features:

Real-time Streaming: Watch agent responses appear character-by-character
Step Visualization: See Task Extraction → Classification → Orchestration → Execution in real-time
15+ Built-in Themes: Switch themes instantly with Ctrl+T
Command Palette: Quick access to all actions with Ctrl+P
Slash Commands: /exit, /caps:on, /caps:off, and more
Query History: Navigate previous queries with up/down arrows
Content Viewer: Multi-tab view for prompts and responses
Todo Visualization: See agent planning progress

Keyboard Shortcuts:

Shortcut	Action
`Ctrl+P`	Open command palette
`Ctrl+T`	Open theme picker
`Ctrl+L`	Focus input
`Ctrl+H`	Toggle help panel
`Ctrl+C` (twice)	Exit TUI
`Space`/`b`	Scroll down/up
`g`/`G`	Go to top/bottom

Installation:

pip install osprey-framework[tui]

Interactive Menu:

The TUI is also accessible from the interactive menu as “chat (tui)”

Usage#

The chat interface provides an interactive session with your agent:

Agent Configuration loaded successfully.
Registry initialized with 25 capabilities
⚡ Use slash commands (/) for quick actions - try /help

You: What's the weather in San Francisco?

Agent: [Processing request...]
The current weather in San Francisco is 18°C with partly cloudy conditions.

Slash Commands#

The CLI supports slash commands for agent control and interface operations:

Agent Control Commands:

/planning:on          # Enable planning mode
/planning:off         # Disable planning mode
/approval:enabled     # Enable approval workflows
/approval:disabled    # Disable approval workflows
/approval:selective   # Enable selective approval

Performance Commands:

/task:off            # Bypass task extraction
/caps:off            # Bypass capability selection

Direct Chat Mode Commands:

/chat                     # List capabilities that support direct chat
/chat:<capability_name>   # Enter direct chat mode with a specific capability
/exit                     # Exit direct chat mode (or exit CLI if not in direct chat)

CLI Commands:

/help                # Show available commands
/help <command>      # Show help for specific command
/exit                # Exit direct chat mode (or exit CLI if not in direct chat)
/clear               # Clear the screen

Direct Chat Mode#

Direct Chat Mode enables multi-turn conversations directly with a specific capability, bypassing the normal orchestration pipeline (task extraction → classification → orchestration). This is useful for:

Interactive exploration with ReAct-style capabilities
Focused conversations where you know which capability you need
Context accumulation across multiple turns within the same capability

Available Capabilities:

Direct chat mode is designed for ReAct-style capabilities - agents that use tools and benefit from multi-turn reasoning. The framework includes one built-in direct-chat capability:

state_manager - Inspect and manage accumulated context data

You can create your own ReAct capabilities with direct chat support. One example is generating a capability from an MCP server - see MCP Capability Generation for a tutorial that creates the weather_mcp capability shown in these examples.

Entering Direct Chat Mode:

👤 You: /chat
Available capabilities for direct chat:
┌──────────────────┬─────────────────────────────────────┐
│ Capability       │ Description                         │
├──────────────────┼─────────────────────────────────────┤
│ state_manager    │ Manage and inspect agent state      │
│ weather_mcp      │ Weather operations via MCP server   │
└──────────────────┴─────────────────────────────────────┘

👤 You: /chat:weather_mcp
✓ Entering direct chat with weather_mcp
  Type /exit to return to normal mode

🎯 weather_mcp > What's the weather in Tokyo?
🤖 The current weather in Tokyo is 22°C with clear skies...

🎯 weather_mcp > How about San Francisco?
🤖 San Francisco is currently 18°C with partly cloudy conditions...

Note

The weather_mcp capability shown above is an example generated from an MCP server. Your /chat list will only show state_manager until you generate or create additional direct-chat-enabled capabilities.

Key Behaviors:

Message history preserved: The capability sees the full conversation history, enabling follow-up questions like “How about yesterday?” or “Compare that to Boston”
Pipeline bypass: Messages go directly to the capability without task extraction, classification, or orchestration
Visual indicator: The prompt changes to show the active capability (e.g., 🎯 weather_mcp >)

Saving Results to Context:

While in direct chat mode, you can save results for later use in orchestrated queries:

🎯 weather_mcp > What's the weather in Tokyo?
🤖 Tokyo is 22°C with clear skies...

🎯 weather_mcp > Save that as tokyo_weather
🤖 ✓ Saved weather data as 'tokyo_weather'

🎯 weather_mcp > /exit
✓ Exited direct chat with weather_mcp

👤 You: Compare the tokyo_weather to current Boston conditions
🤖 [Orchestrated query using saved context...]

State Manager Capability:

The built-in state_manager capability provides tools for inspecting and managing accumulated context:

👤 You: /chat:state_manager
✓ Entering direct chat with state_manager

🎯 state_manager > What context data do we have?
🤖 Current context includes:
   - WEATHER_RESULTS: tokyo_weather, sf_weather
   - ANALYSIS_RESULTS: correlation_analysis

🎯 state_manager > Show me the tokyo_weather details
🤖 [Displays full context object...]

Exiting Direct Chat Mode:

Use /exit to return to normal orchestrated mode:

🎯 weather_mcp > /exit
✓ Exited direct chat with weather_mcp
  Returning to normal mode

👤 You: [Now in normal orchestrated mode]

Note

Not all capabilities support direct chat mode. Only capabilities with direct_chat_enabled = True appear in the /chat list. See Building Your First Capability for how to enable this on your own capabilities.

osprey config#

Manage project configuration settings. All configuration-related operations are unified under this command group following industry standard CLI patterns (git config, docker config, etc.).

If no subcommand is provided, launches an interactive configuration menu.

Subcommands#

osprey config show - Display current project configuration
osprey config export - Export framework default configuration
osprey config set-control-system - Switch control system connector (mock/epics/tango)
osprey config set-epics-gateway - Configure EPICS gateway settings
osprey config set-models - Configure AI provider and models for all model roles

Syntax#

osprey config [SUBCOMMAND] [OPTIONS]

Examples#

Launch interactive config menu:

osprey config

Show current configuration:

osprey config show

Export framework defaults:

osprey config export

Switch to EPICS:

osprey config set-control-system epics

Configure AI models:

osprey config set-models

osprey config show#

Display current project configuration with syntax highlighting.

Syntax#

osprey config show [OPTIONS]

Options#

--project PATH / -p PATH: Project directory to use. If not specified, uses current directory or OSPREY_PROJECT env var.
--format FORMAT: Output format: yaml (default) or json

Examples#

# Show current project's config
osprey config show

# Show specific project's config
osprey config show --project ~/my-agent

# Export as JSON
osprey config show --format json

osprey config export#

Export the Osprey framework’s default configuration template.

This shows the complete framework template with all available options and default values. Useful for understanding what configuration options are available.

Syntax#

osprey config export [OPTIONS]

Options#

--output PATH / -o PATH: Save configuration to file instead of printing to console.
--format FORMAT: Output format: yaml (default) or json

Examples#

# Display to console
osprey config export

# Save to file
osprey config export -o defaults.yml

# Export as JSON
osprey config export --format json -o defaults.json

# Use as reference when customizing
osprey config export --output reference.yml
diff reference.yml config.yml

osprey config set-control-system#

Switch control system connector type (mock, epics, tango, labview).

This changes the control_system.type setting in config.yml, which determines which connector is used at runtime for control system operations.

Note

Pattern detection is control-system-agnostic. This setting only affects which connector is loaded at runtime, not which patterns are used for security detection.

Syntax#

osprey config set-control-system SYSTEM_TYPE [OPTIONS]

Arguments#

SYSTEM_TYPE: Control system type: mock, epics, tango, or labview

Options#

--project PATH / -p PATH: Project directory to use. If not specified, uses current directory.

Examples#

# Switch to mock mode (development)
osprey config set-control-system mock

# Switch to EPICS (production)
osprey config set-control-system epics

# Switch to Tango
osprey config set-control-system tango

osprey config set-epics-gateway#

Configure EPICS gateway address and port settings.

Can use facility presets (ALS, APS) or specify custom gateway settings.

Syntax#

osprey config set-epics-gateway [OPTIONS]

Options#

--facility FACILITY: Facility preset: als, aps, or custom
--address ADDRESS: Gateway address (required for custom facility)
--port PORT: Gateway port (required for custom facility)
--project PATH / -p PATH: Project directory to use. If not specified, uses current directory.

Examples#

# Use ALS gateway preset
osprey config set-epics-gateway --facility als

# Use APS gateway preset
osprey config set-epics-gateway --facility aps

# Set custom gateway
osprey config set-epics-gateway --facility custom \
    --address gateway.example.com --port 5064

osprey config set-models#

Configure AI provider and models for all model roles.

Updates ALL model configurations in config.yml to use the specified provider and model. This includes orchestrator, response, classifier, and any custom models defined in your project (e.g., channel_write, channel_finder).

The max_tokens settings for each model role will be preserved.

If no options are provided, launches an interactive selection menu.

Syntax#

osprey config set-models [OPTIONS]

Options#

--provider PROVIDER: AI provider: anthropic, openai, google, cborg, or ollama
--model MODEL: Model identifier (e.g., claude-sonnet-4, gpt-4, anthropic/claude-haiku)
--project PATH / -p PATH: Project directory to use. If not specified, uses current directory.

Examples#

# Interactive mode (recommended)
osprey config set-models

# Set all models to Anthropic Claude
osprey config set-models --provider anthropic --model claude-sonnet-4

# Set all models to CBORG provider for specific project
osprey config set-models --provider cborg --model anthropic/claude-haiku --project ~/my-agent

osprey tasks#

Browse and manage AI assistant tasks. Tasks are structured workflows for common development activities like testing, code review, and documentation.

Syntax#

osprey tasks [COMMAND] [OPTIONS]

Commands#

osprey tasks (no subcommand)

Launch interactive task browser with actions like open in editor, copy to project, and install as Claude Code skill.

osprey tasks list

Quick non-interactive list of all available tasks.

osprey tasks copy TASK_NAME

Copy a task to your project’s .ai-tasks/ directory for use with any AI assistant.

Options:: --force / -f - Overwrite existing files

osprey tasks show TASK_NAME

Print a task’s instructions to stdout.

osprey tasks path TASK_NAME

Print the path to a task’s instructions file.

Examples#

# Interactive browser (recommended)
osprey tasks

# List all tasks
osprey tasks list

# Copy task to project for any AI assistant
osprey tasks copy pre-merge-cleanup

# View instructions
osprey tasks show testing-workflow

# Get path (useful for scripting)
osprey tasks path create-capability

Using Tasks#

After copying a task to your project, reference it in your AI assistant:

@.ai-tasks/testing-workflow/instructions.md Help me write tests

See AI-Assisted Development for detailed workflow guides.

osprey claude#

Manage Claude Code skill installations. Skills are task wrappers that enable Claude Code to automatically discover and use Osprey workflows.

Syntax#

osprey claude [COMMAND] [OPTIONS]

Commands#

osprey claude install TASK

Install a task as a Claude Code skill in .claude/skills/<task>/.

Skills can be installed from two sources:

Custom wrappers - Pre-built skill files in integrations/claude_code/<task>/
Auto-generated - Generated from task frontmatter if skill_description is present

Options:: --force / -f - Overwrite existing installation

osprey claude list

List installed and available Claude Code skills.

Shows:

Installed skills in current project
Available skills (custom wrappers)
Auto-generatable skills (from task frontmatter)
Tasks without skill support

Examples#

# List available and installed skills
osprey claude list

# Install a skill
osprey claude install create-capability

# Force reinstall
osprey claude install testing-workflow --force

Output:

Claude Code Skills

Installed in this project:
  ✓ create-capability

Available to install:
  ○ migrate
  ○ testing-workflow (auto-generated)
  ○ ai-code-review (auto-generated)

Tasks without skill support (use @-mention or add skill_description):
  - comments
  - release-workflow

Skill Auto-Generation#

Tasks with skill_description in their frontmatter can be installed as skills without requiring custom wrappers:

---
workflow: my-task
skill_description: >-
  Description of when Claude should use this skill.
  Include keywords users might say.
---

When installed, the skill is auto-generated from this frontmatter.

See AI-Assisted Development for complete workflow documentation.

osprey export-config (DEPRECATED)#

Deprecated since version Use: osprey config export instead. This command is kept for backward compatibility but will be removed in a future version.

Export the framework’s default configuration for reference.

Syntax#

osprey export-config [OPTIONS]

Migration#

Replace osprey export-config with osprey config export:

# Old (deprecated)
osprey export-config
osprey export-config -o file.yml

# New (recommended)
osprey config export
osprey config export -o file.yml

Use Cases#

Discover available options - See all configuration fields and their defaults
Reference template - Use as starting point for custom configurations
Troubleshooting - Compare your config with framework defaults
Documentation - Understand configuration structure

Configuration Structure#

The exported configuration includes:

Models: LLM provider configurations (orchestrator, classifier, code generator)
Services: Jupyter, OpenWebUI, Pipelines settings
Execution Control: Timeouts, retry policies, safety limits
File Paths: Directory structures and artifact locations
Logging: Log levels and output settings

Interactive Configuration#

New in v0.9.6: Interactive Configuration Management

The interactive menu now includes a configuration submenu for managing project settings. Access it via: Project Menu → config → Choose action

Available Configuration Actions#

When you select config from the project menu, you get access to:

1. Show Configuration

Display current project configuration (equivalent to osprey config show)

2. Set Control System Type

Switch between Mock (tutorial/development) and EPICS (production) connectors

Automatically updates control_system.type
Optionally updates archiver.type
Shows current configuration before changes
Provides next-step guidance

3. Set EPICS Gateway

Configure EPICS gateway for production deployment

APS preset: pvgatemain1.aps4.anl.gov:5064
ALS preset: cagw-alsdmz.als.lbl.gov:5064 (read), 5084 (write)
Custom: Interactive prompts for your facility
Automatically detects current facility configuration

Example Workflow#

Tutorial → Production Migration:

1. Create project (starts in Mock mode by default)
   $ osprey init my-control-assistant --template control_assistant

2. Develop with Mock data (no hardware needed)
   $ osprey chat
   You: "What is the beam current?"

3. When ready for production, launch interactive menu:
   $ osprey

4. Select your project → config → set-control-system
   → Choose: EPICS - Production mode
   → Choose: Yes - Use EPICS Archiver Appliance
   → Confirm changes

5. Configure EPICS gateway:
   config → set-epics-gateway
   → Choose: ALS (or APS, or Custom)
   → Confirm changes

6. Test production connection:
   $ osprey chat
   You: "What is the beam current?"

What Changes Under the Hood:

The interactive commands update your config.yml:

# Before (Tutorial Mode)
control_system:
  type: mock
archiver:
  type: mock_archiver

# After (Production Mode)
control_system:
  type: epics
  connector:
    epics:
      gateways:
        read_only:
          address: cagw-alsdmz.als.lbl.gov  # From facility preset
          port: 5064
archiver:
  type: epics_archiver

Your capabilities work unchanged - ConnectorFactory automatically uses the configured connector.

See Also:

Migrate to Production Control System in Control Assistant Part 3
Control System Integration for connector architecture

Environment Variables#

The framework uses environment variables for API keys, paths, and deployment-specific configuration.

For a complete list of all supported environment variables with descriptions and examples, see the Environment Variables section in the Installation Guide.

Quick Reference:

# Required
PROJECT_ROOT=/path/to/your/project
OPENAI_API_KEY=sk-...          # Or ANTHROPIC_API_KEY, GOOGLE_API_KEY, CBORG_API_KEY

# Optional - Multi-project support (New in v0.7.7)
OSPREY_PROJECT=/path/to/project

# Optional - Other settings
LOCAL_PYTHON_VENV=/path/to/venv
TZ=America/Los_Angeles
CONFIG_FILE=custom-config.yml

# Proxy settings (if needed)
HTTP_PROXY=http://proxy:8080
NO_PROXY=localhost,127.0.0.1

OSPREY_PROJECT

Default project directory for all commands. Allows working with a specific project from any location without using the --project flag on every command.

Priority: Lower than --project flag, higher than current directory.

Example:

export OSPREY_PROJECT=~/projects/my-agent
osprey chat           # Uses ~/projects/my-agent
osprey deploy status  # Uses ~/projects/my-agent

Common Workflows#

Complete Project Setup#

# 1. Install framework
pip install osprey-framework

# 2. Create project
osprey init weather-agent --template hello_world_weather
cd weather-agent

# 3. Configure environment
cp .env.example .env
# Edit .env with your API keys

# 4. Update config (optional)
# Edit config.yml as needed

# 5. Deploy services
osprey deploy up --detached

# 6. Start chat
osprey chat

Development Workflow#

# Start services for development
osprey deploy up

# In another terminal, make changes to your code
# Test with chat interface
osprey chat

# Rebuild containers if needed
osprey deploy rebuild

# Clean up
osprey deploy clean

Framework Development Workflow#

If you’re developing the framework itself:

# Start services with local framework
osprey deploy up --dev

# Make changes to framework code
# Rebuild to test changes
osprey deploy rebuild --dev

# Verify local framework is used
podman exec jupyter-read pip show osprey

Multi-Project Workflows#

New in v0.7.7: Multi-Project Support

Work with multiple projects simultaneously using the --project flag or FRAMEWORK_PROJECT environment variable.

Scenario 1: Parallel Development

Work on multiple projects from a central location:

# Check status of all projects
osprey deploy status --project ~/projects/weather-agent
osprey deploy status --project ~/projects/turbine-monitor
osprey deploy status --project ~/projects/als-assistant

# Start chat with specific project
osprey chat --project ~/projects/weather-agent

Scenario 2: Dedicated Terminal per Project

Use environment variables for persistent project selection:

# Terminal 1: Weather Agent
export OSPREY_PROJECT=~/projects/weather-agent
osprey deploy up --detached
osprey chat

# Terminal 2: Turbine Monitor
export OSPREY_PROJECT=~/projects/turbine-monitor
osprey deploy up --detached
osprey health

# Terminal 3: Jump between projects
osprey chat --project ~/projects/weather-agent
osprey chat --project ~/projects/turbine-monitor

Scenario 3: CI/CD Pipeline

Automate deployment and testing across multiple projects:

#!/bin/bash
# Deploy and test multiple projects

PROJECTS=(
    ~/projects/weather-agent
    ~/projects/turbine-monitor
    ~/projects/als-assistant
)

for project in "${PROJECTS[@]}"; do
    echo "Deploying $project..."
    osprey deploy up --detached --project "$project"
    osprey health --project "$project"
done

Scenario 4: Development + Production

Work with development and production configurations:

# Development environment
export OSPREY_PROJECT=~/dev/my-agent
osprey deploy up

# In another terminal, check production
osprey deploy status --project /opt/production/my-agent

Configuration Reference#

# View framework defaults
osprey config export

# Export to file for reference
osprey config export --output defaults.yml

# Create new project and compare configs
osprey init test-project
diff defaults.yml test-project/config.yml

Troubleshooting#

Command Not Found#

If osprey command is not found:

# Verify installation
pip show osprey-framework

# Reinstall if needed
pip install --upgrade osprey-framework

# Check pip bin directory is in PATH
python -m pip show osprey-framework

Services Won’t Start#

# Check podman is running
podman --version
podman ps

# Check for port conflicts
lsof -i :8080
lsof -i :9099

# Try starting services in foreground to see errors
osprey deploy up

Configuration Errors#

# Validate against framework defaults
osprey config export --output defaults.yml

# Check your config syntax
cat config.yml

# Ensure environment variables are set
cat .env

Chat Not Responding#

# Verify services are running
osprey deploy status
podman ps

# Check API keys are set
cat .env

# Verify model configuration
grep -A 10 "models:" config.yml

CLI Reference#

Overview#

Interactive Mode#

Context-Aware Menus#

Interactive Project Creation#

Disabling Interactive Mode#

Global Options#

--project / -p#

--version#

--help#

CLI Customization#

Commands#

osprey init#

Syntax#

Arguments#

Options#

Examples#

Generated Structure#

osprey generate#

Subcommands#

osprey generate capability#

osprey generate mcp-server#

osprey deploy#

Syntax#

Global Options#

Commands#

Configuration#

Workflow#

Service Access#

osprey chat#

Syntax#

Options#

Examples#

Terminal User Interface (TUI)#

Usage#

Slash Commands#

Direct Chat Mode#

osprey config#

Subcommands#

Syntax#

Examples#

osprey config show#

Syntax#

Options#

Examples#

osprey config export#

Syntax#

Options#

Examples#

osprey config set-control-system#

Syntax#

Arguments#

Options#

Examples#

osprey config set-epics-gateway#

Syntax#

Options#

Examples#

osprey config set-models#

Syntax#

Options#

Examples#

osprey tasks#

Syntax#

Commands#

Examples#

Using Tasks#

osprey claude#

Syntax#

Commands#

Examples#

Skill Auto-Generation#

osprey export-config (DEPRECATED)#

Syntax#

Migration#

Use Cases#

Configuration Structure#

Interactive Configuration#

Available Configuration Actions#

Example Workflow#

`--project` / `-p`#

`--version`#

`--help`#