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 import-github --repo <owner/name> # Import GitHub issues (read-only, 4.0.12+)
trellis import-git-bug --from <git-repo> # Import git-bug issues from refs/bugs/* (4.0.12+)
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
Operator surface (4.0.10+)
trellis note add "<text>" [-t tag] [-r ref] # Capture a note (no commitment)
trellis note list [--all] # Captured notes (--all incl. promoted/archived)
trellis note promote <id> --issue|--epic [--cycle <c>] # Turn a note into work
trellis note archive <id> # Retire a note without promoting
trellis wip # Active / queue / shipped / next / cycles / notes
trellis cycle create <alias> --target <date> # Time-boxed container with a deadline
trellis cycle add <cycle> <issue...> # Membership is a link
trellis cycle list | show <id> | close <id>
trellis telos add <alias> # Strategic root
trellis telos root <epic> <telos> # Epic : [rootedIn]→ telos
trellis cadence [--note-days N] [--lanes] [--dispatch] # Derived due-check (exits 1 when due)
trellis mirror [<path>] [--write|--check] # Generate / verify a derived index
trellis report [-d N|--day] # Derived worklog + epic→telos rollup
Notes capture without commitment; promotion is the only act that creates an
issue. wip, cadence, mirror, and report are derived: recomputed from
the graph, never hand-maintained.
cadence --lanes (4.0.12+) folds lane hygiene (stale/abandoned lanes) into
the due-check; --dispatch implies --lanes and executes the lane
dispositions (runs the lane gc sweep). This is the repo-aware sweep the tenant
cron cannot run, since lanes are VCS-engine-scoped.
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>
trellis guard <path> [--agent <id>] [--exclude-lane <id>] [--json] # Cross-agent file-ownership check (4.0.12+)
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>/.
trellis guard <path> (4.0.12+, ADR 0015) reports whether a write to a file
is permitted under lane-ownership policy and exits 1 when denied: a thin CLI
surface so host hooks and the OS enforce the identical rule. --exclude-lane
(default $TRELLIS_LANE_ID) names the writer's own lane, so any remaining owner
is a foreign lane; without it, ownership falls back to the agent id.
Presence & census (4.0.12+)
trellis who [--census] [--scope <path>] [--stale <ms>] [--json] # Agents in this repo
trellis agents [--scope <path>] [--stale <ms>] [--json] # Census a directory tree
trellis presence [announce|clear] [--client <c>] [--status <s>] # Manage this session's heartbeat
trellis who lists agents currently working in the repo from ambient
presence heartbeats; --census merges harness-native activity (opencode DB,
Claude Code) with the ledger. trellis agents is the repo-wide census
(ADR 0052), rendering harness · identity · model · work · age; the same view via
who --census. trellis presence announce|clear writes or clears this
session's heartbeat; --client tags the harness and --status is
active | idle | away.
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>]
trellis git journal catch-up [-b <branch>] [--json] # Absorb disk→op-log drift as ops (4.0.12+)
Auto-runs after successful lane promote when git.syncOnPromote is true. See
Git Bridge.
trellis git journal catch-up scans the working tree and journals any
disk→op-log divergence as ops; the reverse of materialization (git edits → op
log). It refuses silently if a path is unreconcilable (exit 1, with
--json for machine output); -b, --branch advances a branch head to the last
journaled op.
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
WebContainer sandbox (4.0.1+)
Run the Trellis CLI inside StackBlitz WebContainer in the browser. Distinct from Trellis Cloud E2B sandboxes.
trellis sandbox serve [--port 4321] [--host 127.0.0.1] [-P <trellis-root>]
trellis sandbox pack [-o public/bootstrap.json] [-P <trellis-root>]
serve requires npm run build first. pack writes bootstrap JSON for static
deploy (Vercel). See WebContainer sandbox.
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