CLI Reference

`trurlic init`

Create a .trurlic/ directory in the current project.

trurlic init

Generates project.toml, empty components/, decisions/, patterns/ directories, a .state/ directory for session persistence, and an initial graph.toml. Adds .trurlic/.state/ to .gitignore. Safe to run in an existing project — refuses to overwrite if .trurlic/ already exists.

`trurlic add component`

Define a new component in the architecture graph.

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

Argument	Description
`name`	Kebab-case component name (e.g. `auth`, `rate-limiter`)
`-d`, `--description`	One-line description of what this component does

Component names must be unique, non-empty, and valid kebab-case. Reserved names (project, all) are rejected.

`trurlic add connection`

Connect two components with a directional edge representing data or control flow.

trurlic add connection <from> <to>

Both components must already exist. Self-connections are rejected. Duplicate connections are idempotent (no error, no duplicate edge).

`trurlic rename component`

Rename a component, updating all references atomically.

trurlic rename component <old> <new>

Updates the component file, all decisions referencing it, all patterns, all connections, and the graph index — in a single atomic commit.

`trurlic remove component`

Remove a component from the graph.

trurlic remove component <name>

Refuses if any decisions reference this component. Remove or reassign decisions first.

`trurlic remove decision`

Remove a decision from the graph.

trurlic remove decision <name>

The name is the decision filename without .toml (e.g. auth-jwt-with-dpop-binding). Refuses if other decisions depend on it (DependsOn edges) or if removing it would shrink a pattern below two members. Reports affected patterns and edges.

`trurlic remove connection`

Remove a connection between two components.

trurlic remove connection <from> <to>

`trurlic decide`

Record a quick decision without the full Socratic flow.

trurlic decide <component> \
  --choice "..." \
  --reason "..." \
  [--supersede <name>] \
  [-a "alternative"]

Flag	Description
`--choice`	What was decided
`--reason`	Why — your reasoning
`--supersede`	Decision name this replaces (filename without `.toml`)
`-a`, `--alternative`	Alternative considered and rejected (repeatable)

`trurlic design`

Start a Socratic design conversation for a component.

trurlic design <component> \
  [--continue] [--revisit] \
  [-t <task>] \
  [-p <provider>] [-m <model>]

Flag	Description
`--continue`	Resume a previously interrupted session
`--revisit`	Revisit and potentially revise existing decisions
`-t`, `--task`	Task description to focus the conversation
`-p`, `--provider`	LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `custom`, `ollama`
`-m`, `--model`	Model override

Requires an API key (except Ollama). See Configuration.

`trurlic bootstrap`

Show bootstrap progress and agent instructions for autonomous architecture extraction.

trurlic bootstrap [<component>] [-p <provider>] [-m <model>]

Without -p: prints status and agent instructions. With -p: runs the bootstrap directly via the LLM API.

`trurlic serve`

Start the MCP server for AI coding agent integration.

trurlic serve

Runs on stdio transport. Watches .trurlic/ for external changes. No API key required.

`trurlic install`

Write MCP server configuration for an IDE or coding agent.

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

Flag	Description
`--ide`	Target IDE (see table below)
`--binary-path`	Path to the trurlic binary to embed in the config (default: current executable)
`--dry-run`	Print the config snippet to stdout without writing to disk

Supported targets

Target	IDE / Agent	Config path
`claude`	Claude Desktop (Anthropic)	Platform-specific `claude_desktop_config.json`
`claude-code`	Claude Code (Anthropic)	Runs `claude mcp add` directly
`cursor`	Cursor IDE	`~/.cursor/mcp.json`
`cline`	Cline (VS Code extension)	Platform-specific `cline_mcp_settings.json`
`windsurf`	Windsurf (Codeium)	`~/.codeium/windsurf/mcp_config.json`
`copilot`	GitHub Copilot (VS Code)	Platform-specific `Code/User/mcp.json`
`codex`	Codex CLI (OpenAI)	`~/.codex/config.toml`
`opencode`	OpenCode	`~/.config/opencode/opencode.json`
`openclaw`	OpenClaw (MCPorter)	`~/.openclaw/workspace/config/mcporter.json`
`hermes-agent`	Hermes Agent (NousResearch)	`~/.hermes/config.yaml`
`antigravity`	Antigravity CLI (Google)	`~/.gemini/config/mcp_config.json`

Existing configuration files are preserved — trurlic install merges the Trurlic server entry into the existing config. If a trurlic entry already exists, it is overwritten with a warning.

Examples

trurlic install --ide cursor              # write config for Cursor
trurlic install --ide claude-code         # register via `claude mcp add`
trurlic install --ide copilot --dry-run   # preview the config snippet

`trurlic map`

Open the interactive graph visualization in the browser.

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

Flag	Description
`--port`	Bind to a specific port (default: OS-assigned)
`--no-open`	Start server without opening the browser
`--detach`	Background the server; print URL and exit

`trurlic status`

Show project status: component count, decision count, health summary.

trurlic status

`trurlic check`

Validate .trurlic/ internal consistency.

trurlic check [--rebuild]

Flag	Description
`--rebuild`	Force-rebuild `graph.toml` from node files (nuclear recovery). Non-inferable edges (`ConnectsTo`, `DependsOn`, etc.) will be lost.

Verifies BLAKE3 hashes, checks for dangling edges, validates schemas, and detects cycles.

Global options

trurlic --version          # print version
trurlic --help             # print help
trurlic <command> --help   # print help for a specific command