CLI Commands - Runtools.ai

Some commands below are aspirational (template, schedule, aip, agent chat, dev, sync). The implemented commands are: login, logout, auth, init, deploy, sandbox (full CRUD + watch), ssh-key (CRUD), tool (search, install, exec, publish, delete, credentials), secret (set, list, delete), and agent (run, list, get, delete). See the CLI Overview for the accurate command list.

Global Options

Flag	Description
`--help, -h`	Show help
`--version, -v`	Show version
`--json`	Output as JSON
`--quiet, -q`	Suppress output
`--verbose`	Verbose output

Project Scaffolding

Init

Scaffold a new RunTools project in the current directory:

runtools init [options]

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

Or use npx:

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

This generates a project with:

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.config.ts — Project-level configuration
agents/ — Directory for agent definitions
- Single file: agents/assistant.ts
- Folder with entry point: agents/support-bot/index.ts
Ready to run with runtools dev

Sandboxes

Create

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)

Examples:

# 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

List

runtools sandbox list [options]

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

Get

runtools sandbox get <id>

SSH

runtools sandbox ssh <id>

Exec

runtools sandbox exec <id> <command>

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

Logs

runtools sandbox logs <id> [options]

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

URL

runtools sandbox url <id> [options]

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

Sync

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

Pause/Resume

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

Snapshot

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

Destroy

runtools sandbox destroy <id>

Templates

List

runtools template list [options]

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

Create

runtools template create [options]

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

Status

runtools template status <slug>

Logs

runtools template logs <slug> [options]

Options:
  --follow, -f           Stream build logs

Delete

runtools template delete <slug>

Agents

Create Agent

Create a new agent definition file:

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

List Agents

runtools agent list                      # List agents in current project

Push to Dashboard

Push agents to the dashboard for preview:

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

Pushed agents appear in your dashboard as drafts. Use the dashboard or runtools deploy to publish to production.

Deploy to Production

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

Run 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

Interactive Chat

runtools agent chat <agent>

# Opens interactive chat session

Run Agent

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

Interactive Chat

runtools agent chat <deployment>

# Opens interactive chat session

Code Execution

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

Tools

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

Secrets

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

# List secrets
runtools secret list

# Delete secret
runtools secret delete <name>

Schedules

# 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>

AIP Hub

Sessions

# 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>

Context Blocks

# 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

Search

# 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

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

Local Development

Dev

Start local development with automatic backend detection:

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

Smart Backend Detectionruntools dev automatically detects the best local backend:

Environment	Backend	Features
Linux + KVM	Firecracker	Full (pause/resume, snapshots)
WSL2 + nested virt	Firecracker	Full (pause/resume, snapshots)
Mac / Windows	Docker	Limited (no pause/resume)

Use --cloud to force cloud sandbox with full features regardless of local environment.

Sync

runtools sync [options]

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

# Example:
runtools sync --watch

Project Config

Create runtools.config.ts in your project root:

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',
  },
});

The CLI automatically uses this config for runtools dev, runtools push, and runtools deploy.

CLI Reference

​Global Options

​Project Scaffolding

​Init

​Sandboxes

​Create

​List

​Get

​SSH

​Exec

​Logs

​URL

​Sync

​Pause/Resume

​Snapshot

​Destroy

​Templates

​List

​Create

​Status

​Logs

​Delete

​Agents

​Create Agent

​List Agents

​Push to Dashboard

​Deploy to Production

​Run Agent

​Interactive Chat

​Run Agent

​Interactive Chat

​Code Execution

​Tools

​Secrets

​Schedules

​AIP Hub

​Sessions

​Context Blocks

​Search

​Invoke

​Local Development

​Dev

​Sync

​Project Config

Global Options

Project Scaffolding

Init

Sandboxes

Create

List

Get

SSH

Exec

Logs

URL

Sync

Pause/Resume

Snapshot

Destroy

Templates

List

Create

Status

Logs

Delete

Agents

Create Agent

List Agents

Push to Dashboard

Deploy to Production

Run Agent

Interactive Chat

Run Agent

Interactive Chat

Code Execution

Tools

Secrets

Schedules

AIP Hub

Sessions

Context Blocks

Search

Invoke

Local Development

Dev

Sync

Project Config