Skip to main content

​
CLI Overview

The Stoneforge CLI (sf) is the primary command-line interface for managing agents, tasks, and orchestration workflows. While the web dashboard is the main interface for human operators, the CLI is heavily used by agents internally and provides full programmatic access to the platform.

​
Installation

npm install -g @stoneforge/smithy
The CLI is installed as part of the @stoneforge/smithy package.

​
Command Structure

sf <command> <subcommand> [arguments] [options]
Examples: 
sf serve                              # Start server + dashboard
sf agent register MyWorker --role worker
sf task create --title "Fix bug" --priority 1
sf daemon start

​
Global Options

These options are available for all commands:
​
--db
string
Path to SQLite database file (default: .stoneforge/stoneforge.db)
​
--actor
string
Entity ID of the actor performing the operation (default: operator)
​
--json
boolean
Output results in JSON format
​
--quiet
boolean
Minimal output (IDs only, no formatting)
​
--verbose
boolean
Verbose output with additional debug information
​
--help
boolean
Show help for a command

​
Output Modes

The CLI supports three output modes:

​
Standard Mode (default)

Human-readable tables and formatted text: 
sf agent list

ID            NAME         ROLE      STATUS   SESSION
el-abc123     MyWorker     worker    idle     -
el-def456     MainDir      director  running  a1b2c3d4

2 agent(s)

​
JSON Mode

Machine-readable JSON output for scripting: 
sf agent list --json

[
  {
    "id": "el-abc123",
    "name": "MyWorker",
    "type": "entity",
    "metadata": {
      "agent": {
        "agentRole": "worker",
        "sessionStatus": "idle"
      }
    }
  }
]

​
Quiet Mode

Minimal output (just IDs) for piping: 
sf agent list --quiet

el-abc123
el-def456

​
Command Categories

​
Server & Runtime

  • sf serve — Start orchestrator server + web dashboard
  • sf daemon start|stop|status|sleep|wake — Control the dispatch daemon

​
Initialization

  • sf init — Initialize a Stoneforge workspace in the current project

​
Agent Management

  • sf agent register|start|stop|list|show|stream — Manage orchestrator agents
  • sf pool create|list|show|update|delete|status — Manage agent pools

​
Task Management

  • sf task create|list|ready|close|reopen — Create and manage tasks
  • sf task assign|defer|undefer|describe — Task operations

​
Git Operations

  • sf merge — Squash-merge branches (used by agents for task completion)

​
Common Workflows

​
Start the Orchestrator

# Initialize workspace
cd your-project
sf init

# Start server + dashboard
sf serve

# Open dashboard at http://localhost:3457
open http://localhost:3457

​
Register and Start an Agent

# Register a worker agent
sf agent register MyWorker --role worker --mode ephemeral

# Start the agent with a prompt
sf agent start el-abc123 --prompt "Work on assigned tasks"

# Start with streaming output
sf agent start el-abc123 --stream

​
Manage Tasks

# List ready tasks
sf task ready

# Create a new task
sf task create --title "Implement login" --priority 1 --type feature

# Show task details
sf task show el-task123

# Close a task
sf task close el-task123 --reason "Completed in PR #42"

​
Control the Dispatch Daemon

# Start the daemon (auto-assigns tasks to idle workers)
sf daemon start

# Check status
sf daemon status

# Stop the daemon
sf daemon stop

​
Exit Codes

The CLI uses standard exit codes:
CodeMeaning
0Success
1General error
2Invalid arguments
3Validation error
4Not found
5Conflict (e.g., duplicate)

​
Environment Variables

The CLI respects these environment variables:
  • STONEFORGE_DB — Default database path (overridden by --db)
  • STONEFORGE_ACTOR — Default actor entity ID (overridden by --actor)

​
Next Steps

Agent Commands

Register, start, stop, and manage orchestrator agents

Task Commands

Create, list, and manage tasks

Daemon Commands

Control the dispatch daemon

Serve Command

Start the orchestrator server and web dashboard

Build docs developers (and LLMs) love

Get started for freeTalk to us