sf init Initialize a Stoneforge workspace by creating the .stoneforge/ directory with database, configuration, and required files.
Usage Run this command in the root of your project to set up Stoneforge.
What Gets Created When you run sf init, the following structure is created:
.stoneforge/ ├── stoneforge.db # SQLite database (auto-created) ├── elements.jsonl # JSONL export file (empty initially) ├── dependencies.jsonl # JSONL export file (empty initially) ├── config.yaml # Configuration file └── .gitignore # Ignores DB files and runtime state
Default Configuration The generated config.yaml includes:
# Stoneforge Configuration # Default actor for operations (optional) # actor: my-agent # Database path (relative to .stoneforge/) database : stoneforge.db # Sync settings sync : auto_export : true elements_file : elements.jsonl dependencies_file : dependencies.jsonl # Playbook search paths playbooks : paths : - playbooks # Identity settings identity : mode : soft
Default Operator Entity The database is initialized with a default operator entity:
ID : el-0000Name : operatorType : human
This entity is used as the default actor for CLI operations and represents the human operator.
Options Custom database path (default: .stoneforge/stoneforge.db)
Overwrite existing workspace (destructive)
Skip creating .gitignore file
Examples Basic Initialization Output: ✓ Created .stoneforge/ directory ✓ Initialized database at .stoneforge/stoneforge.db ✓ Created default operator entity (el-0000) ✓ Generated config.yaml ✓ Created .gitignore Workspace initialized successfully! Next steps: 1. sf serve Start the server and dashboard 2. sf agent register Register your first agent
Custom Database Path sf init --db custom/path/db.sqlite
Reinitialize (Overwrite Existing) This will delete all existing data in your workspace!
After Initialization Once initialized, you can:
Start the server :
Register agents :sf agent register Director --role director
Create tasks :sf task create --title "First task"
Configuration You can customize the generated config.yaml:
Auto-Export Control JSONL export behavior:
sync : auto_export : true # Export after every mutation elements_file : elements.jsonl dependencies_file : dependencies.jsonl
Identity Mode Configure signing requirements:
identity : mode : soft # Options: soft, hard, disabled
soft : Verify signatures when present, allow unsignedhard : Require signatures on all operationsdisabled : No signature verification
Playbook Paths Define where to search for playbook templates:
playbooks : paths : - playbooks - .stoneforge/playbooks - ~/stoneforge-playbooks
Git Integration The default .gitignore excludes:
# Runtime data *.db *.db-journal *.db-wal *.db-shm daemon-state.json # Logs logs/ *.log
Track JSONL files in Git : The elements.jsonl and dependencies.jsonl files should be committed to Git as the source of truth for your project state.
Troubleshooting Directory Already Exists If .stoneforge/ already exists:
Error: .stoneforge directory already exists Use --force to overwrite
Solution: sf init --force # Destructive - deletes existing data
Or manually remove:
rm -rf .stoneforge sf init
Permission Denied If you get a permission error:
Error: EACCES: permission denied, mkdir '.stoneforge'
Solution: Ensure you have write permissions in the current directory.Database Already Open If the database is locked:
Error: database is locked
Solution: Stop any running sf serve or agent processes:sf daemon stop pkill -f "sf serve"
Serve Start orchestrator server
Agent Commands Register and manage agents