Command Reference
Complete reference for every Trellis CLI command.
Repository Setup
trellis init [--path <dir>] # Initialize a new repo
trellis seed [--ide cursor|windsurf] # Refresh agent context files
trellis repair # Repair corrupted .trellis/ops.json
trellis doctor # Probe mutation safety (3.4.0+)
trellis import --from <git-repo> # Import Git history as milestones
trellis export --to <dir> # Export milestones to Git commits
Most repo commands accept -p, --path <dir>. When omitted, Trellis walks up
from the current directory to the nearest .trellis root (monorepo subfolders
work without passing the root path).
Working
trellis status # Current branch, op count, pending changes
trellis log [--limit N] # Op stream history
trellis files # All tracked files
trellis watch # Start continuous file watching
Branches
trellis branch # List branches
trellis branch <name> # Create + switch to branch
trellis branch -d <name> # Delete a branch
Milestones & Checkpoints
trellis milestone create -m "message" # Create milestone
trellis milestone create -m "msg" --commit # Create + git commit on integration (3.4.0+)
trellis milestone create -m "msg" --from <hash> --to <hash> # Over a specific range
trellis milestone list # List milestones
trellis checkpoint create # Manual checkpoint
trellis checkpoint list # List checkpoints
Diff & Merge
trellis diff [from] [to] # File-level diff
trellis merge <branch> [--dry-run] # Three-way merge
trellis parse <file> # Semantic parse (declarations, imports)
trellis sdiff <fileA> <fileB> # Semantic diff between two versions
Identity
trellis identity # Show current identity
trellis identity init --name "Ada" # Create identity (person scope, default)
trellis identity init --name "Ada" --local # Legacy repo-scope identity
trellis identity import # Adopt an exported identity
trellis identity export # Machine-readable identity JSON
Identities are person-scoped by default (~/.trellis/identity.json), created at first-run onboarding (trellis init — new/existing/skip). Repo identities are a legacy fallback.
Pairing (3.2.6+; device registry person-scoped in 3.4.2+)
trellis pair start [--no-qr] # Challenge + QR payload (needs an identity)
trellis pair join <payload> [--kind <k>] [--transport <t>]
trellis pair approve <join-payload> --yes # Verify fingerprint, then authorize
trellis pair accept <auth-payload> # Finish on the joining device
trellis pair list # Kind, transport, sync state, last seen
trellis pair show <deviceId> # Full device record
trellis pair revoke <deviceId> [--push <ws-url>] # Revoke (+ notify peers)
Terminal QR rendering uses uqr when stdout is a TTY. Device keys never touch identity.json — the root key stays on the approving device. Devices follow the person: the registry lives in ~/.trellis/devices and is shared across all clones of your identity.
Idea Garden
trellis garden # List abandoned clusters
trellis garden list [--status <s>] [--file <f>] # Filter clusters
trellis garden show <cluster-id> # Inspect a cluster
trellis garden search --keyword <term> # Search by keyword
trellis garden revive <cluster-id> # Revive cluster as branch
trellis garden stats # Garden statistics
Issue Tracking
trellis issue create -t "Title" -P high -l label # Create issue
trellis issue create -t "Title" --parent TRL-5 # Sub-task under epic
trellis issue create -t "Title" --description "…" # --description alias for --desc
trellis issue list [--status <s>] # List/filter issues
trellis issue show TRL-1 # Issue details
trellis issue active # Currently active issues
trellis issue triage TRL-1 # Move backlog → queue
trellis issue start TRL-1 # Start (auto-branch + lane)
trellis issue start TRL-1 --no-lane # Start without agent lane
trellis issue pause TRL-1 -n "Waiting on review" # Pause
trellis issue resume TRL-1 # Resume
trellis issue update TRL-1 [options] # Update metadata
trellis issue update TRL-1 --parent TRL-5 # Re-parent sub-task
trellis issue update TRL-1 --clear-parent # Remove parent link
trellis issue describe TRL-1 "description" # Set description
trellis issue assign TRL-1 --agent <name> # Assign to agent
trellis issue ac TRL-1 "criterion" [--command "…"] # Add acceptance criterion
trellis issue ac-rm TRL-1 <index> # Retract criterion (3.4.0+)
trellis issue ac-pass TRL-1 <criterion-id> # Mark criterion passed
trellis issue ac-fail TRL-1 <criterion-id> # Mark criterion failed
trellis issue check TRL-1 # Run acceptance criteria
trellis issue readiness TRL-1 # Completion readiness summary
trellis issue block TRL-1 --blocked-by TRL-2 # Mark blocked
trellis issue unblock TRL-1 --blocked-by TRL-2 # Remove block
trellis issue close TRL-1 --confirm # Close issue
trellis issue reopen TRL-1 # Reopen closed issue
Agent Lanes
Isolated op journals for multi-agent work. Each lane forks from the integration
branch head and promotes explicitly into main (or another target branch).
Defaults (3.2.5+): trellis init writes lanes.worktreeBind: true and
git.syncOnPromote: true:
{
"lanes": { "worktreeBind": true },
"git": { "syncOnPromote": true, "remote": "origin" }
}
Full guide: Agent coordination.
trellis lane create [--from main] [--issue TRL-N] [--session <id>] [--worktree <path>]
trellis lane split [--session <id>] # Domain lane without issue (3.4.0+)
trellis lane ensure --session <id> [--enter] [--issue TRL-N] # session isolation (hooks)
trellis lane fork <parentId> [--session <id>] [--child]
trellis lane list [--active] [--stale]
trellis lane enter <id>
trellis lane leave
trellis lane status [id]
trellis lane diff <id> [--to main]
trellis lane promote <id> [--dry-run] [--explain] [--require-test] [--force-lock]
trellis lane lock-status
trellis lane watch [--port 3939] [--no-open] # SSE dashboard
trellis lane drop <id>
export TRELLIS_LANE_ID=lane-…
export TRELLIS_SESSION_ID=…
export TRELLIS_EDIT_ROOT=/path/to/worktree
issue start creates and enters a lane by default (--no-lane to skip).
Promote before close if using --no-promote. When worktree bind is on, edit
under .trellis/worktrees/<shortId>/.
Git mirror
Trellis owns semantics on the op-log; git owns file bytes (4.0+). Do not
git stash inside agent workflows.
trellis git sync [--push] [--path <dir>]
Auto-runs after successful lane promote when git.syncOnPromote is true. See
Git Bridge.
Test manifest
trellis test [suite] [--list]
trellis issue check TRL-1 [--suite <id>]
trellis lane promote <id> --require-test
Suites defined in .trellis/tests.json (seeded on init). Default promote gate
includes smoke and check (pnpm run check) as of 3.4.0.
Protocol & re-entry
trellis protocol send --parent TRL-N --from <role> --to <role> --re TRL-N --status HANDOFF --body "…"
trellis whereami
trellis whereami checkpoint
Entity Graph
trellis entity create -i <id> -t <type> -a key=value # Create entity
trellis entity get <id> [--json] # Get entity details
trellis entity update <id> -a key=value # Update attributes
trellis entity delete <id> # Delete entity
trellis entity list [-t <type>] # List entities
trellis fact add <id> <attribute> <value> # Add fact
trellis fact remove <id> <attribute> <value> # Remove fact
trellis fact query [-e <id>] [-a <attribute>] # Query facts
trellis link add <source> <attribute> <target> # Add link
trellis link remove <source> <attribute> <target> # Remove link
trellis link query [-e <id>] [-a <attribute>] # Query links
References
trellis refs <file> # Outgoing wiki-link refs in a file
trellis refs --backlinks TRL-5 # Files referencing an entity
trellis refs --broken # Broken and stale references
trellis refs --stats # Reference index statistics
Decision Traces
trellis decision list [--tool <pattern>] # List decisions
trellis decision show DEC-1 # Show full trace
trellis decision chain issue:TRL-5 # Decision chain for entity
Sync
trellis sync status # Local sync state
trellis sync reconcile --remote <path> # Reconcile with another repo
Peer push/pull transport commands are not exposed yet; they are tracked on
the roadmap.
Query & Search
trellis query <eql> # TQL query
trellis db query <eql> # Trellis DB query
trellis ask "authentication code" # Semantic search
trellis ask "show me auth code" --rag # RAG context output
trellis search <pattern> # Full-text search across tracked files
trellis reindex # Rebuild search index
Trellis Studio
Launch the local IDE from a Trellis repo (delegates to the turtlecode CLI when
installed):
trellis studio [--path <dir>] [--port <n>] [--new] [--no-open]
Alias: trellis web. Initializes the repo first unless --no-init is passed.
Trellis DB
Use Trellis as a local application database:
trellis db init [--path .trellis-db] [--port 3000] # Initialize config + storage
trellis db serve # Start HTTP + WebSocket server
trellis db query <eql> # Query entities
trellis db create <type> [json] # Create entity
trellis db read <id> # Read entity
trellis db list # List entities
trellis db deploy --name <sprite> # Deploy to Sprites
See the Trellis DB API for the full server surface.
Ontology
trellis ontology list # List ontologies
trellis ontology inspect <id> # Show details
trellis ontology validate # Validate store