CLI Overview

The sf command-line interface is the primary way to interact with Stoneforge. While agents use the CLI internally, human operators typically use the web dashboard — but the CLI is essential for setup, debugging, and scripting.

Installation

npm

npm install -g @stoneforge/quarry

pnpm

pnpm add -g @stoneforge/quarry

From source

git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
pnpm install && pnpm build
pnpm link --global --filter @stoneforge/quarry

Verify it works:

sf --version

Initializing a workspace

Run sf init in your project root to create a .stoneforge/ directory:

sf init --name my-project

This creates:

• .stoneforge/config.yaml — project configuration
• .stoneforge/stoneforge.db — local SQLite database
• .stoneforge/playbooks/ — playbook definitions
• .stoneforge/.gitignore — excludes the database from version control

If .stoneforge/ already exists (e.g. after cloning a repo) but no database is present, sf init creates the database and auto-imports from existing JSONL sync files.

Global flags

These flags work with any sf command:

Flag	Description
--help, -h	Show help
--version, -V	Show version
--json	Output as JSON (machine-readable)
--quiet, -q	Minimal output (IDs only)
--verbose, -v	Enable debug output
--actor <name>	Specify acting entity
--from <name>	Alias for --actor
--db <path>	Override database path
--sign-key <key>	Private key for signing (base64 PKCS8)
--sign-key-file <path>	Path to file containing private key

Tip

The --json flag is useful for piping output to tools like jq. The --quiet flag returns only IDs — great for scripting: sf create task --title "Fix bug" -q | xargs sf show.

Command aliases

Many commands have shorter aliases for convenience:

Alias	Maps to
add, new	create
rm, remove	delete
ls	list
s, get	show
todo, tasks	ready
done, complete	close
st	status
dep	dependency
msg	message
doc	document

Common workflows

Create and manage tasks

# Create a task
sf create task --title "Implement auth" --priority 1

# List open tasks
sf task list --status open

# See ready tasks (unblocked)
sf task ready

# Close a task
sf task close <id>

Work with dependencies

# Block task B on task A
sf dep add <taskA> <taskB>

# View the dependency tree
sf dep tree <id>

Sync with collaborators

# Export changes to JSONL sync files
sf export

# Check sync status
sf status

# Import changes from sync files
sf import

Start the dashboard

# Start the orchestrator server + dashboard
sf serve

# Or start just the data platform
sf serve quarry --port 3456

Getting help

Every command supports --help:

sf --help           # Top-level help
sf task --help      # Task subcommand help
sf dep add --help   # Specific command help

For the complete list of every command and flag, see the Command Reference.