CLI Commands

Detailed reference for all Shuttl CLI commands.

shuttl dev

Run agents in development mode with a local web UI.

shuttl dev [app|dir] [flags]

shuttl dev starts your app, opens http://127.0.0.1:5757 in your browser, and restarts the app whenever a source file changes. The app command comes from the app field in shuttl.json. Pass a project directory to load that folder's shuttl.json and use it as the working directory (~ is expanded). Pass an app command string to override shuttl.json.

Flags

Examples

# Basic usage (reads "app" from shuttl.json)
shuttl dev

# Run a project from another directory
shuttl dev ./apps/marketing/agents
shuttl dev ~/code/my-agents

# Pass the app command directly
shuttl dev "npx tsx src/main.ts"

# Listen on all interfaces (LAN access)
shuttl dev --host 0.0.0.0 --port 8080

# Same as above, host:port form
shuttl dev --host 0.0.0.0:8080

# Run on a random free port without opening a browser (e.g. over SSH)
shuttl dev --port 0 --no-open

# Legacy terminal UI
shuttl dev --tui

Web UI layout

Click any node in the graph to filter the Logs tab to that node and see its most recent input/output. Click a trigger node to invoke it with a custom payload. The graph and bottom panel can each be collapsed, and the divider between them dragged.

Auto-restart

The CLI watches your project directory (respecting .gitignore, and always ignoring node_modules, .git, dist and build). When files change, the app is restarted and the graph refreshed. Any runs that were in flight are marked aborted in the log. Use Restart in the top bar to restart manually, or --no-watch to turn watching off.

Execution tracing

When run under shuttl dev, @shuttl-io/core (v0.6+) attaches a trace envelope to every event so that tool calls, sub-agent runs and outcomes are attributed to the right graph node. Older versions of the library still work: the UI falls back to a coarser view where every event is attributed to the agent as a whole.

shuttl serve

Run agents in production mode with three operating modes.

shuttl serve [flags]

Flags

Mode 1: Serve All Agents

# Serve all agents on HTTP
shuttl serve

# With SSL
shuttl serve --ssl-cert ./cert.pem --ssl-key ./key.pem

# Custom port
shuttl serve --port 443

Mode 2: Serve Specific Agent or Trigger

# Serve only the SupportBot agent
shuttl serve --agent SupportBot

# Serve only API triggers (no scheduled tasks)
shuttl serve --trigger api

# Serve only rate/cron triggers (worker mode)
shuttl serve --trigger rate

# Combine: specific agent with specific trigger
shuttl serve --agent SupportBot --trigger api

Mode 3: Invoke and Exit

For serverless/cron deployments, invoke a trigger once and exit:

# Invoke the rate trigger for DailyReporter
shuttl serve --invoke --agent DailyReporter --trigger rate

Use this for AWS Lambda, Cloud Functions, or Kubernetes CronJobs.

Differences from dev

See the Deployment Guide for detailed deployment patterns.

shuttl build

Build agents for deployment.

shuttl build [flags]

Flags

Examples

# Build with defaults
shuttl build

# Custom output directory
shuttl build --output ./build

Output

Creates a deployable bundle with a full manifest:

dist/
├── manifest.json    # Complete deployment manifest
├── agents.json      # Agent definitions
├── triggers.json    # Trigger configurations
├── outcomes.json    # Outcome configurations
└── bundle.js        # Compiled code (if applicable)

The manifest.json contains all trigger and outcome configurations, helping you determine which infrastructure to provision for self-hosting. See the Deployment Guide for details.

shuttl generate

Generate a new Shuttl AI agent project with all necessary scaffolding.

shuttl generate <name> --language <lang> [flags]

Flags

Supported Languages

Examples

# Create a TypeScript project
shuttl generate my-agent --language typescript

# Create a Python project
shuttl generate my-agent -l python

# Create a Go project without installing dependencies
shuttl generate my-agent -l go --skip-install

What Gets Generated

The command creates a complete project structure:

=== "TypeScript"

```
my-agent/
├── src/
│   └── agent.ts         # Basic agent example
├── package.json         # Dependencies
├── tsconfig.json        # TypeScript config
└── shuttl.json          # Shuttl configuration
```

=== "Python"

```
my-agent/
├── src/
│   └── agent.py         # Basic agent example
├── pyproject.toml       # Dependencies
└── shuttl.json          # Shuttl configuration
```

=== "Go"

```
my-agent/
├── main.go              # Entry point
├── agent.go             # Basic agent example
├── go.mod               # Go modules
└── shuttl.json          # Shuttl configuration
```

shuttl login

Authenticate with Shuttl Cloud (for deployment features).

shuttl login [flags]

Flags

Examples

# Interactive login (opens browser)
shuttl login

# Token-based login (for CI/CD)
shuttl login --token $SHUTTL_TOKEN

Authentication Flow

1. Opens browser to https://shuttl.dev/auth
2. Authenticate with GitHub/Google
3. Token stored in ~/.shuttl/credentials

shuttl version

Display version and build information.

shuttl version [flags]

Flags

Examples

# Full version info
shuttl version
# Output:
# Shuttl CLI v1.0.0
# Built: 2025-01-03
# Go: go1.21.0
# Commit: abc1234

# Version number only
shuttl version --short
# Output:
# 1.0.0

Environment Reference

Required Variables

Optional Variables

Exit Codes

Troubleshooting

Common Issues

??? question "Port already in use" ```bash # Find what's using the port lsof -i :5757

# Use a different port (or 0 for a random free port)
shuttl dev --port 3001
```

??? question "Config file not found" ```bash # Check current directory ls -la shuttl.json

# Specify path explicitly
shuttl dev --config ./path/to/shuttl.json
```

??? question "Permission denied on binary" bash chmod +x ./shuttl

??? question "Command not found after install" Add to your PATH: bash export PATH="$HOME/.local/bin:$PATH"

Next Steps

• 🚀 Quick Start - Get started with Shuttl
• 🧠 Core Concepts - Learn the architecture
• 🔍 Examples - Real-world usage