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
Copy

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]
Copy

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
Copy

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
Copy

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"
Copy

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
Copy

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
Copy

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
Copy

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
Copy

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
Copy

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
Copy

---

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"
Copy

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
Copy

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
Copy

---

Update Command

Check for and install CLI updates:

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

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
Copy

---

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/
Copy

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"]
    }
}
Copy

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
Copy

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