CLI Commands

runtools init [options]

Options:
  --template <name>      Start from a template (default: basic)
  --name <name>          Project name
  --agent                Include agent boilerplate

npx create-runtools-app my-app
cd my-app

my-app/
├── runtools.config.ts       # Project configuration
├── agents/
│   ├── assistant.ts         # Simple agent (single file)
│   └── support-bot/         # Complex agent (folder)
│       ├── index.ts         # Entry point
│       ├── tools.ts         # Custom tools
│       └── prompts.ts       # System prompts
├── package.json
└── tsconfig.json

runtools sandbox create [options]

Options:
  --template <name>      Template to use (default: nodejs-20)
  --name <name>          Sandbox name
  --mount <id:path>      Mount persistent storage (repeatable)
  --idle-timeout <sec>   Auto-pause after idle (default: 600)
  --vcpus <n>            Number of vCPUs
  --memory <size>        Memory (e.g., 4GB)
  --disk <size>          Disk size (e.g., 50GB)

# Ephemeral sandbox (no mounts)
runtools sandbox create --template nodejs-20

# With persistent mount
runtools sandbox create --template nodejs-20 --mount my-project:/workspace

# Multiple mounts
runtools sandbox create --template python-ml \
  --mount my-code:/workspace \
  --mount datasets:/data

runtools sandbox list [options]

Options:
  --status <status>      Filter by status (running, paused, stopped)
  --limit <n>            Max results

runtools sandbox get <id>

runtools sandbox ssh <id>

runtools sandbox exec <id> <command>

# Examples:
runtools sandbox exec sandbox-abc123 "npm run build"
runtools sandbox exec sandbox-abc123 "ls -la"

runtools sandbox logs <id> [options]

Options:
  --follow, -f           Stream logs
  --lines <n>            Number of lines (default: 100)

runtools sandbox url <id> [options]

Options:
  --port <port>          Port number (default: 3000)

runtools sandbox sync <local> <id>:<remote> [options]

Options:
  --watch, -w            Watch for changes
  --ignore <patterns>    Ignore patterns

# Example:
runtools sandbox sync ./src sandbox-abc123:/workspace/src --watch

runtools sandbox pause <id>
runtools sandbox resume <id>

runtools sandbox snapshot <id> --name <name>
runtools sandbox rollback <id> --to <snapshot>
runtools sandbox branch <id> --from <snapshot> --name <name>

runtools sandbox destroy <id>

runtools template list [options]

Options:
  --type <type>          Filter: system, custom

runtools template create [options]

Options:
  --config <file>        Config file (template.yaml)
  --dockerfile <file>    Dockerfile path
  --slug <slug>          Template slug

runtools template status <slug>

runtools template logs <slug> [options]

Options:
  --follow, -f           Stream build logs

runtools template delete <slug>

runtools agent create [name] [options]

Options:
  --template <type>      Agent template (basic, coding, research)

# Examples:
runtools agent create                    # Interactive
runtools agent create code-assistant     # Creates agents/code-assistant.ts

runtools agent list                      # List agents in current project

runtools push [agent] [options]

Options:
  --all                  Push all agents (default if no agent specified)

# Examples:
runtools push                            # Push all agents
runtools push code-assistant             # Push specific agent

runtools deploy [agent] [options]

Options:
  --all                  Deploy all agents (default if no agent specified)

# Examples:
runtools deploy                          # Deploy all agents
runtools deploy code-assistant           # Deploy specific agent

runtools agent run <agent> <message> [options]

Options:
  --stream               Stream output
  --json                 Output as JSON
  --timeout <sec>        Timeout in seconds

# Example:
runtools agent run code-assistant "Create a todo app" --stream

runtools agent chat <agent>

# Opens interactive chat session

runtools agent run <deployment> <message> [options]

Options:
  --stream               Stream output
  --json                 Output as JSON
  --timeout <sec>        Timeout in seconds

# Example:
runtools agent run my-code-bot "Create a todo app" --stream

runtools agent chat <deployment>

# Opens interactive chat session

runtools exec [options] <code>

Options:
  --runtime <runtime>    python, node, bun, go, rust
  --file <file>          Execute file instead
  --entry <file>         Entry point (with --file)
  --timeout <ms>         Timeout

# Examples:
runtools exec --runtime python "print(1 + 1)"
runtools exec --runtime node "console.log('hello')"
runtools exec --runtime python --file script.py

# List installed tools
runtools tool list

# Install tool
runtools tool install <name>

# Configure tool
runtools tool configure <name>

# Uninstall tool
runtools tool uninstall <name>

# Search marketplace
runtools tool search <query>

# Execute tool
runtools tool exec <name> <action> [params]

# Set secret
runtools secret set <name> <value>

# List secrets
runtools secret list

# Delete secret
runtools secret delete <name>

# Create schedule
runtools schedule create [options]
  --deployment <slug>    Deployment slug
  --cron <expression>    Cron expression
  --message <msg>        Message to send

# List schedules
runtools schedule list

# Delete schedule
runtools schedule delete <id>

# List sessions
runtools aip sessions

# Create session
runtools aip session create --name "Auth Feature"

# Get session details
runtools aip session get <session-id>

# Fork session with filtered context
runtools aip session fork <session-id> --include-tags auth,security

# Delete session
runtools aip session delete <session-id>

# List blocks in a session
runtools aip blocks --session <session-id>

# Create a note block
runtools aip block create --session <session-id> \
  --type note \
  --content "User prefers TypeScript"

# Pin a block
runtools aip block pin <block-id>

# Tag a block
runtools aip block tag <block-id> --tags auth,decision

# Semantic search across all context
runtools aip search "How does authentication work?"

# Search within specific session
runtools aip search "JWT token handling" --session <session-id>

# Search with tag filter
runtools aip search "database schema" --tags architecture,postgres

# Invoke agent with session context
runtools aip invoke <agent> --session <session-id> "Continue the auth implementation"

# Invoke with context filters
runtools aip invoke code-assistant \
  --session <session-id> \
  --include-tags auth \
  --exclude-tags deprecated \
  "Add refresh token support"

runtools dev [agent] [options]

Options:
  --cloud                Force cloud sandbox (always full features)
  --docker               Force Docker (no pause/resume)
  --port <port>          Local port for dev server proxy
  --no-sync              Disable file sync

# Examples:
runtools dev                             # All agents, auto-detect backend
runtools dev code-assistant              # Specific agent
runtools dev --cloud                     # Force cloud sandbox

runtools sync [options]

Options:
  --watch, -w            Watch for changes
  --ignore <patterns>    Ignore patterns

# Example:
runtools sync --watch

import { defineConfig } from '@runtools/cli';

export default defineConfig({
  project: {
    name: 'my-app',
    org: 'my-org',           // Optional: organization slug
  },
  
  // Default template for all agents
  defaultTemplate: 'nodejs-20',
  
  // Agents directory (default: ./agents)
  agentsDir: './agents',
  
  // Dev settings
  dev: {
    sync: ['./src:/workspace/src'],
    ignore: ['node_modules', '.git', 'dist'],
  },
  
  // Environment variables
  env: {
    NODE_ENV: 'development',
  },
});