CLI Reference

Overview

The Sulala CLI is the command-line interface for Agent OS. Use it when the sulala package is installed (e.g. from the repo as bun run cli -- <args> or via the built binary sulala).

Requirements: Bun. The CLI and server both require Bun.

Commands

version

sulala version
sulala -v
sulala --version

Prints the Agent OS version (from package.json).

start

sulala start           # Foreground: run the server (same as bun run dev / bun run index)
sulala start --daemon  # Background: spawn server, write PID to ~/.agent-os/sulala.pid

When run with --daemon, the server runs in the background. Use sulala stop to stop it.

stop

sulala stop

Reads the PID from ~/.agent-os/sulala.pid and sends SIGTERM to that process. Use only when the server was started with sulala start --daemon.

onboard

sulala onboard

First-time setup:

• Creates ~/.agent-os/ (or AGENT_OS_HOME)
• Creates config.json with placeholder keys (API keys, channel tokens, etc.)
• Ensures database directory exists
• Seeds agents from seed dir (e.g. data/agents) if the DB is empty
• Installs system agents and system skills from seed dirs

Run once after install. After that, use update to add new system agents/skills.

update

sulala update

Requires an existing database (run sulala onboard first). Loads the same DB, then installs system agents and system skills from the seed directories (e.g. data/agents, data/skills). Skips items that already exist. Use after pulling new default agents or skills from the repo.

run

sulala run <agent_id> <task>

Example:

sulala run echo_agent "What is 2+2?"
sulala run personal_agent "Summarize my calendar for today"

Runs the given agent with the provided task text. Uses the same database as the server when present (AGENT_MEMORY_DB_PATH or ~/.agent-os/database.db), so dashboard agents are available. Output is printed to stdout; on error, exits with code 1.

help

sulala help
sulala -h
sulala --help

Prints usage and command list.

Environment variables (CLI & server)

Examples

# First-time setup
sulala onboard

# Start server in foreground
sulala start

# Start server in background
sulala start --daemon

# Stop background server
sulala stop

# Run an agent
sulala run personal_agent "What's the weather in Tokyo?"

# Update system agents and skills
sulala update

# Show version
sulala version