CLI Reference

The trurlic CLI manages the decision graph and starts the servers. It is fully offline and never calls an LLM — all agent reasoning happens over MCP. Run trurlic <command> --help for inline help.

Command	Purpose
`init`	Create `.trurlic/` in the current project
`add component` / `add connection`	Add a component or a directional connection
`rename component`	Rename a component, updating all references atomically
`remove component` / `remove decision` / `remove connection`	Remove a node or edge
`decide`	Record a decision directly
`query file`	Find decisions that constrain a file or directory
`status`	Show component/decision counts and open issues
`check`	Validate `.trurlic/` consistency
`gc`	Reclaim decisions that lost their anchor
`migrate`	Migrate `.trurlic/` to the current format version
`serve`	Start the MCP server
`map`	Open the interactive graph in the browser
`install`	Write MCP config for an IDE

init

trurlic init

Creates project.toml, an initial graph.toml, empty components/ decisions/ patterns/, and a .state/ scratch dir; adds .trurlic/.state/ to .gitignore. Refuses if .trurlic/ already exists.

add component

trurlic add component <name> [-d <description>]

name must be unique, valid kebab-case, and not a reserved name (project, all). -d/--description sets a one-line summary.

add connection

trurlic add connection <from> <to>

Directional edge (data/control flow). Both components must exist; self-connections are rejected; duplicates are idempotent.

rename component

trurlic rename component <old> <new>

Updates the component file, every referencing decision and pattern, all connections, and the index — in one atomic commit.

remove component

trurlic remove component <name>

Refuses if any decision references the component.

remove decision

trurlic remove decision <name>                       # one decision
trurlic remove decision --agent --component <name>   # all agent decisions in a component

name is the decision filename without .toml. Refuses if other decisions DependsOn it or if removal would shrink a pattern below two members; reports affected patterns and edges. The --agent batch is atomic — if any removal is cascade-blocked, none happen.

remove connection

trurlic remove connection <from> <to>

decide

Record a decision directly, without a design conversation.

trurlic decide <component> \
  --choice "..." --reason "..." \
  [-a "alternative"]... \
  [--ref "src/auth/token.rs::issue_token"]...

Flag	Description
`--choice`	What was decided
`--reason`	Why — your reasoning
`-a`, `--alternative`	An alternative considered and rejected (repeatable)
`--ref`	Code location this decision manifests: `file` or `file::symbol` (repeatable)

Use project as the component for a project-wide rule. Recorded with attribution=user.

query file

trurlic query file <path>

Lists decisions whose code_refs match path exactly or fall under it (directory prefix) — e.g. src/store/write.rs or src/store. Use it to find which decisions constrain a file before you edit it.

status

trurlic status

Component and decision counts plus open issues (uncovered concerns, unreviewed agent decisions).

check

trurlic check [--rebuild]

Verifies BLAKE3 hashes, dangling edges, schemas, and cycles. --rebuild reconstructs graph.toml from node files (nuclear recovery) — non-inferable edges (ConnectsTo, DependsOn, Constrains, Supersedes) are lost and must be re-added.

gc

Reclaim decisions that have lost their anchor: orphaned (component gone), orphaned-ref (all referenced files deleted), or long-unreviewed agent decisions.

trurlic gc                      # dry-run: report what would be reclaimed (DEFAULT)
trurlic gc --apply              # write the removals (orphans only)
trurlic gc --aggressive --apply # also remove orphaned-ref + unreviewed agent decisions

Dry-run is the default. --aggressive widens the scope; combined with --apply it prompts for confirmation unless --yes is passed (required in CI / non-interactive shells).

migrate

trurlic migrate [--dry-run]

Upgrades .trurlic/ to the current format version. --dry-run shows what would change without writing.

serve

trurlic serve

Starts the MCP server over stdio. Watches .trurlic/ for external changes. No API key required. See MCP Server.

map

trurlic map [--port <N>] [--no-open] [--detach]

Opens the interactive graph. --port binds a specific port (default: OS-assigned); --no-open skips launching the browser; --detach backgrounds the server and prints the URL.

install

Write MCP server configuration for an IDE or agent.

trurlic install --ide <target> [--binary-path <path>] [--dry-run]

--binary-path overrides the binary embedded in the config (default: the running executable); --dry-run prints the snippet without writing. Existing configs are merged, not clobbered — an existing trurlic entry is overwritten with a warning.

`--ide` value	Target	Config written
`claude`	Claude Desktop	Platform `claude_desktop_config.json`
`claude-code`	Claude Code	Runs `claude mcp add` directly
`cursor`	Cursor	`~/.cursor/mcp.json`
`cline`	Cline (VS Code)	Platform `cline_mcp_settings.json`
`windsurf`	Windsurf	`~/.codeium/windsurf/mcp_config.json`
`copilot`	GitHub Copilot	Platform `Code/User/mcp.json` (`servers` key)
`codex`	Codex CLI	`~/.codex/config.toml`
`open-code`	OpenCode	`~/.config/opencode/opencode.json`
`open-claw`	OpenClaw (MCPorter)	`~/.openclaw/workspace/config/mcporter.json`
`hermes-agent`	Hermes Agent	`~/.hermes/config.yaml`
`antigravity`	Antigravity CLI	`~/.gemini/config/mcp_config.json`

See Connect Your IDE for details.

Global options

trurlic --version
trurlic --help
trurlic <command> --help