# SmythOS CLI

Command line interface for SmythOS SRE (Smyth Runtime Environment) - an advanced agentic AI platform that provides a comprehensive runtime environment for building and managing AI agents.

## Installation

    pnpm install -g @smythos/cli

## Commands Overview

The SRE CLI provides three main commands:

- `sre agent` - Run SmythOS agent files with various execution modes
- `sre create` - Create new SmythOS projects
- `sre update` - Update the CLI and check for updates

## Agent Command

Run SmythOS agent files (.smyth) with different execution modes.

### Basic Usage

    sre agent <path-to-agent.smyth> [options]

### Available Modes

#### 1. Chat Mode (`--chat`)

Start an interactive chat interface with the agent:

    sre agent ./myagent.smyth --chat
    sre agent ./myagent.smyth --chat claude-3.7-sonnet
    sre agent ./myagent.smyth --chat gpt-4o

Options:

- `--chat` - Start chat with default model (gpt-4o)
- `--chat <model>` - Start chat with specified model

#### 2. Prompt Mode (`--prompt`)

Query the agent with a single prompt:

    sre agent ./myagent.smyth --prompt "What is the weather in Tokyo?"
    sre agent ./myagent.smyth --prompt "Analyze this data" claude-3.7-sonnet

Options:

- `--prompt <text>` - Send a prompt to the agent
- `--prompt <text> <model>` - Send a prompt using specific model

#### 3. Skill Execution (`--skill`)

Execute a specific skill from the agent:

    sre agent ./myagent.smyth --skill getUserInfo
    sre agent ./myagent.smyth --skill processData input="sample data" format="json"
    sre agent ./myagent.smyth --skill ask question="who are you"

Options:

- `--skill <skillname>` - Execute a skill without parameters
- `--skill <skillname> key1="value1" key2="value2"` - Execute skill with parameters

#### 4. Agent Execution Modes (`--mode`)

Control how the agent executes and displays information:

    # Default mode - standard execution
    sre agent ./myagent.smyth --chat --mode default

    # Planner mode - enhanced execution with task management panel
    sre agent ./myagent.smyth --chat --mode planner

Available Modes:

- `--mode default` - Standard agent execution with regular output
- `--mode planner` - Enhanced execution featuring:
  - 🎯 Visual Task Panel: Real-time task tracking on the right side
  - 📋 Status Icons: ✅ completed, ⏳ ongoing, 📝 planned, ❌ failed
  - 🔄 Live Updates: Tasks update as the agent works
  - 🎨 Enhanced Streaming: Special formatting for thinking/planning/code tags

Planner Mode Example:

    sre agent ./myagent.smyth --chat --mode planner

This will show a visual task management panel while the agent executes, perfect for complex multi-step operations.

#### 5. MCP Server Mode (`--mcp`)

Start the agent as an MCP (Model Context Protocol) server:

    sre agent ./myagent.smyth --mcp
    sre agent ./myagent.smyth --mcp stdio
    sre agent ./myagent.smyth --mcp sse 3388

Options:

- `--mcp` - Start MCP server with default settings (stdio)
- `--mcp stdio` - Start MCP server using stdio transport
- `--mcp sse` - Start MCP server using SSE transport (default port 3388)
- `--mcp sse <port>` - Start MCP server using SSE transport on specified port

### Global Options

These options work with all execution modes:

#### Vault Configuration (`--vault`)

Provide a vault file for secure credential storage:

    sre agent ./myagent.smyth --chat --vault ./secrets.vault
    sre agent ./myagent.smyth --skill getUserInfo --vault ./myvault.json

#### Models Configuration (`--models`)

Specify custom models configuration:

    sre agent ./myagent.smyth --chat --models ./custom-models.json
    sre agent ./myagent.smyth --prompt "Hello" --models ./prod-models.json

### Complete Examples

    # Interactive chat with custom vault
    sre agent ./agent.smyth --chat --vault ./secrets.vault

    # Execute skill with parameters and vault
    sre agent ./agent.smyth --skill processData input="test" format="json" --vault ./vault.json

    # One-time prompt with specific model and custom models config
    sre agent ./agent.smyth --prompt "Summarize this data" claude-3.7-sonnet --models ./models.json

    # Start MCP server with vault authentication
    sre agent ./agent.smyth --mcp sse 8080 --vault ./secrets.vault

    # Chat with multiple configurations
    sre agent ./agent.smyth --chat gpt-4o --vault ./vault.json --models ./models.json

## Create Command

Create a new SmythOS project. Supports both interactive and non-interactive (batch) modes.

### Interactive Mode

Run without `--template` and `--res-folder` to use the interactive wizard:

    sre create
    sre create "My AI Project"

The wizard walks through project name, template selection, resources folder location, and API key configuration.

### Batch Mode (Non-Interactive)

Provide both `--template` and `--res-folder` to skip all interactive prompts. This is suitable for LLM-driven workflows (e.g. Claude Code) and CI pipelines.

    sre create "My Agent" --template=empty --res-folder=home
    sre create "My Agent" -t minimal -r project --dir ./my-agent

In batch mode API key prompts are skipped. Environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`) are detected automatically and written to the vault. You can edit the vault file afterwards to add or change keys.

### Options

Flag | Short | Description
--- | --- | ---
`--template <name>` | `-t` | Project template. Enables batch mode when combined with `--res-folder`.
`--res-folder <location>` | `-r` | Resources folder: `home` (~/.smyth) or `project` (.//.smyth). Enables batch mode when combined with `--template`.
`--dir <path>` | `-d` | Target directory for the project. Defaults to `./<project-name>`.
`--help` | `-h` | Show help.

### Available Templates

Alias | Branch | Description
--- | --- | ---
`empty` | `sdk-empty` | Empty project
`minimal` | `code-agent-minimal` | Just the basics to get started
`interactive` | `code-agent-book-assistant` | Chat with one agent
`chat-select` | `interactive-chat-agent-select` | Interactive chat with agent selection
`desktop` | `smythos-electron-starter-project` | Desktop App (Electron)
`android` | `android-mobile-agent` | Android Mobile App (React Native)

Both short aliases and full branch names are accepted.

### Examples

    # Interactive project creation
    sre create

    # Create project with specific name (interactive)
    sre create "Customer Support Bot"

    # Batch mode: empty project with shared resources
    sre create "My Agent" --template=empty --res-folder=home

    # Batch mode: minimal template with project-local resources
    sre create "My Agent" --template=minimal --res-folder=project

    # Batch mode: specify target directory explicitly
    sre create "My Agent" -t empty -r home --dir /tmp/my-agent

## Update Command

Check for and install CLI updates:

    sre update
    sre update --check
    sre update --force
    sre update --package pnpm

Options:

- `--check, -c` - Only check for updates without installing
- `--force, -f` - Force update check and installation
- `--package, -p <manager>` - Specify package manager (npm, pnpm, yarn)

Examples:

    # Check and install updates
    sre update

    # Only check for updates
    sre update --check

    # Force update with specific package manager
    sre update --force --package npm

    # Check updates using yarn
    sre update --check --package yarn

## Global Options

- `--help, -h` - Show help for any command
- `--version` - Show CLI version

## File Formats

- Agent Files: `.smyth` files containing agent configuration and workflows
- Vault Files: `.json` or `.vault` files for secure credential storage
- Models Files: `.json` files defining available LLM models

## Models Configuration

The `--models` flag allows you to specify custom model configurations for your agents. You can provide either:

- Single JSON file: A single `.json` file containing model definitions
- Directory: A directory containing multiple `.json` files (all will be merged)

### Usage Examples

    # Single models file
    sre agent ./myagent.smyth --chat --models ./models.json

    # Directory with multiple model files
    sre agent ./myagent.smyth --chat --models ./models-config/

    # Multiple model files in a directory
    sre agent ./myagent.smyth --skill processData --models ./custom-models/

### Models File Format

Each model configuration file should be a JSON object where keys are model names and values are model configurations:

    {
        "gemma-3-4b": {
            "provider": "OpenAI",
            "label": "gemma-3-4b-it",
            "modelId": "gemma-3-4b-it",
            "features": ["text", "tools"],
            "tokens": 8000,
            "completionTokens": 512,
            "enabled": true,
            "baseURL": "http://localhost:1234/v1",
            "credentials": ["vault"]
        },
        "gemma-3-1b": {
            "provider": "OpenAI",
            "label": "gemma-3-1b-it",
            "modelId": "gemma-3-1b-it",
            "features": ["text", "tools"],
            "tokens": 4096,
            "completionTokens": 512,
            "enabled": true,
            "baseURL": "http://localhost:1234/v1",
            "credentials": ["vault"]
        }
    }

### Model Configuration Properties

- `provider`: The LLM provider (e.g., "OpenAI", "Anthropic", "Google")
- `label`: Display name for the model
- `modelId`: The actual model identifier used by the provider
- `features`: Array of supported features (`["text", "tools"]`)
- `tokens`: Maximum input tokens supported
- `completionTokens`: Maximum completion tokens
- `enabled`: Whether the model is available for use
- `baseURL`: Custom API endpoint (optional)
- `credentials`: Array specifying how to retrieve credentials (`["vault"]`)

### Directory Structure Example

When using a directory, you can organize models by provider or type:

    models-config/
    ├── openai-models.json
    ├── anthropic-models.json
    ├── local-models.json
    └── custom-models.json

All JSON files in the directory will be automatically merged, allowing you to organize your model configurations however you prefer.

## Configuration

The CLI supports various configuration options through:

- Command-line flags
- Environment variables
- Configuration files
- Interactive prompts during project creation

For detailed configuration options and advanced usage, see the SmythOS documentation.

### Reporting Issues

If you face any issues with the CLI or the code, set environment variable LOG_LEVEL="debug" and run your code again. Then share the logs with us, it will help diagnose the problem. You can request help by creating an issue on GitHub