CLI Reference

YosrAI Command-Line Interface for blueprint validation, execution, diagramming, and interactive chat.

Installation

The CLI is included with YosrAI:

pip install yosrai
# CLI available as 'yosrai' command

Global Options

yosrai --help          # Show help
yosrai --version       # Show version

Commands

`yosrai validate`

Validate blueprint files for correctness.

# Validate single file
yosrai validate agent.json

# Validate directory (recursive)
yosrai validate blueprints/ --recursive

# JSON output for CI/CD
yosrai validate agent.json --json

# Quiet mode (no output except errors)
yosrai validate blueprints/ --quiet

Exit Codes: - 0: All blueprints valid - 1: One or more blueprints invalid - 2: Error (file not found, invalid JSON, etc.)

CI/CD Example:

- name: Validate Blueprints
  run: |
    yosrai validate blueprints/ --json > validation.json
    if [ $(jq '.valid' validation.json) = "false" ]; then
      echo "❌ Blueprint validation failed"
      jq '.results[] | select(.valid == false) | .errors' validation.json
      exit 1
    fi

`yosrai run`

Execute agents and workflows from blueprint files.

# Run agent with text input
yosrai run agent.json --input "Hello world"

# Run workflow with JSON input file
yosrai run workflow.json --inputs-file data.json

# Run with inline JSON
yosrai run agent.json --inputs-json '{"query": "test", "format": "json"}'

# Output as JSON
yosrai run agent.json --input "Hello" --json

# Skip validation (faster but riskier)
yosrai run agent.json --input "Hello" --no-validate

Input Formats:

Simple text: --input "Hello world"
JSON file: --inputs-file data.json
Inline JSON: --inputs-json '{"key": "value"}'

Output Modes: - Text (default): Human-readable output - JSON (--json): Structured data for scripting - Quiet (--quiet): Only final result, no status messages

`yosrai diagram`

Generate Mermaid diagrams from workflow blueprints.

# Generate diagram to stdout
yosrai diagram workflow.json

# Save to markdown file
yosrai diagram workflow.json -o docs/workflow.md

# Save to plain text file
yosrai diagram workflow.json -o diagram.txt

Output Formats: - Markdown (.md files): Wrapped in code blocks - Plain text: Raw Mermaid syntax

Usage in Documentation:

## Workflow Diagram

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]


### `yosrai chat`

Interactive AI chat with conversation persistence.

```bash
# Start chat with preset agent
yosrai chat --preset assistant

# Use specific model
yosrai chat --model openai/gpt-4o

# Enable multi-line input
yosrai chat --preset writer --multiline

# Save conversation to file
yosrai chat --preset researcher --save-session research.json

# Resume previous conversation
yosrai chat --load-session research.json

# Custom session name
yosrai chat --session-name "coding_help"

Chat Commands:

/quit, /q      Exit chat
/clear, /c     Clear conversation history
/status, /s    Show conversation statistics
/save          Save current session
/help, /h, ?   Show help

Features: - Automatic history management - Cost tracking per message - Session persistence - Multi-line input support

`yosrai new`

Scaffold new agents and workflows.

# Create agent from preset
yosrai new agent MyAgent --preset researcher

# Create agent with custom model
yosrai new agent MyAgent --preset assistant --model anthropic/claude-3

# Create workflow
yosrai new workflow ContentPipeline

# Create conductor
yosrai new conductor TeamLead --skills researcher,writer --planning

# Create pipeline
yosrai new pipeline BlogFactory --steps outline,write,edit

# Create to specific directory
yosrai new agent MyAgent --output-dir ./agents

# Create blueprint only (no code)
yosrai new agent MyAgent --blueprint-only

# Create code only (no blueprint)
yosrai new agent MyAgent --code-only

# List available presets
yosrai new list-presets

Advanced Usage

Batch Processing

# Process multiple files
for file in data/*.json; do
    echo "Processing $file..."
    yosrai run agent.json --inputs-file "$file" --json > "results/$(basename "$file")"
done

# Parallel processing with cost limits
find data/ -name "*.json" -print0 | xargs -0 -n 1 -P 4 bash -c '
    yosrai run agent.json --inputs-file "$1" --json > "results/$(basename "$1")"
' --

CI/CD Integration

# GitHub Actions example
name: AI Pipeline
on: [push]

jobs:
  validate-and-run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install YosrAI
        run: pip install yosrai[openai]

      - name: Validate Blueprints
        run: yosrai validate blueprints/ --recursive

      - name: Run Tests
        run: yosrai run test_agent.json --inputs-file test_data.json --json

      - name: Generate Documentation
        run: yosrai diagram main_workflow.json -o docs/workflow.md

      - name: Check Costs
        run: |
          COST=$(yosrai run analysis.json --json | jq '.usage.cost')
          echo "Cost: $${COST}"
          if (( $(echo "$COST > 1.00" | bc -l) )); then
            echo "Cost exceeded budget"
            exit 1
          fi

Shell Integration

# Add to PATH (usually automatic with pip install)
export PATH="$PATH:~/.local/bin"

# Create alias for common operations
alias ai-run='yosrai run'
alias ai-chat='yosrai chat --preset assistant'
alias ai-validate='yosrai validate'

# Use in scripts
#!/bin/bash
set -e

# Validate before deployment
ai-validate config/
echo "✅ Blueprints valid"

# Run analysis
RESULT=$(ai-run analyzer.json --inputs-file data.json --json)
COST=$(echo "$RESULT" | jq '.usage.cost')

echo "Analysis complete. Cost: $${COST}"

Configuration Files

# Environment variables
export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"

# Use in scripts
yosrai run agent.json --input "Hello"  # Uses env vars automatically

Command Reference

Global Options

--help     Show help message
--version  Show version

validate Options

PATH          Blueprint file or directory path
-r, --recursive  Validate directories recursively
--json          Output as JSON for CI/CD
--quiet         Suppress output except errors

run Options

BLUEPRINT_FILE    Path to blueprint JSON file
--input TEXT      Simple text input
--inputs-file PATH JSON file containing input data
--inputs-json TEXT JSON string containing input data
--no-validate     Skip blueprint validation
--json            Output results as JSON
--quiet           Suppress status output
--trace           Enable execution tracing
--planning/--no-planning Override planning mode (Conductos)

diagram Options

BLUEPRINT_FILE    Path to workflow blueprint
-o, --output PATH Output file path
--format FORMAT   Diagram format (currently only 'mermaid')
--no-validate     Skip blueprint validation

chat Options

--model MODEL     Model to use (default: openai/gpt-4o-mini)
--preset PRESET   Use preset agent
--api-key KEY     API key (or use environment variable)
--multiline       Enable multi-line input mode
--verbose         Show verbose output
--save-session PATH Save conversation to file
--load-session PATH Load conversation from file
--session-name NAME Custom session identifier

new Options

COMMAND          'agent', 'workflow', 'conductor', 'pipeline'
NAME             Name for new agent/workflow
--preset PRESET  Preset to use for agent/workflow
--model MODEL    Model for agent (default: openai/gpt-4o-mini)
--template TEMPLATE Workflow template (default: linear)
--skills SKILLS  Comma-separated skills (Conductor only)
--steps STEPS     Comma-separated steps (Pipeline only)
--planning       Enable planning mode (Conductor only)
-o, --output-dir DIR Output directory (default: current)
--blueprint-only   Create blueprint only
--code-only        Create code only

Error Handling

Exit Codes

0: Success
1: Validation or execution error
2: CLI usage error or file not found

Error Messages

# File not found
yosrai validate missing.json
# Error: Blueprint file not found: missing.json

# Invalid JSON
yosrai validate invalid.json
# Error: Invalid JSON in invalid.json: Expecting ','

# Invalid blueprint
yosrai validate bad.json
# Error: Blueprint validation failed: missing required field 'type'

Debugging

# Enable verbose output
export YOSRAI_VERBOSE=1

# Check version and installation
yosrai --version

# Test basic functionality
yosrai validate --help

Performance Tips

Fast Validation

# Skip expensive checks for quick validation
yosrai validate blueprints/ --quiet

Batch Processing

# Process many files efficiently
yosrai run agent.json --inputs-file large_dataset.json --json --no-validate

Memory Management

# For large conversations, use file-based persistence
yosrai chat --save-session chat.json  # Saves periodically

Integration Examples

Python Scripts

import subprocess
import json

def validate_blueprints(directory):
    result = subprocess.run([
        'yosrai', 'validate', directory, '--json'
    ], capture_output=True, text=True)

    if result.returncode != 0:
        raise Exception(f"Validation failed: {result.stderr}")

    return json.loads(result.stdout)

def run_blueprint_with_cost_tracking(blueprint, inputs):
    result = subprocess.run([
        'yosrai', 'run', blueprint,
        '--inputs-json', json.dumps(inputs),
        '--json'
    ], capture_output=True, text=True)

    if result.returncode != 0:
        raise Exception(f"Execution failed: {result.stderr}")

    return json.loads(result.stdout)

Docker Integration

FROM python:3.11-slim

RUN pip install yosrai[openai]

COPY blueprints/ /app/blueprints/
COPY scripts/ /app/scripts/

WORKDIR /app

# Validate on build
RUN yosrai validate blueprints/

CMD ["yosrai", "run", "main_agent.json", "--input", "Start processing"]

API Integration

from fastapi import FastAPI, HTTPException
import subprocess
import json

app = FastAPI()

@app.post("/run-blueprint")
async def run_blueprint(blueprint_path: str, inputs: dict):
    try:
        result = subprocess.run([
            "yosrai", "run", blueprint_path,
            "--inputs-json", json.dumps(inputs),
            "--json"
        ], capture_output=True, text=True, check=True)

        return json.loads(result.stdout)
    except subprocess.CalledProcessError as e:
        raise HTTPException(status_code=500, detail=e.stderr)

This CLI provides a powerful interface for AI development workflows, from quick prototyping to production deployment and monitoring.