CLI reference

Overview

Command	Description
`loko validate`	Compile and report diagnostics with file, line and column
`loko fmt`	Canonical formatting, like `terraform fmt`
`loko build`	Render diagrams, markdown and a site into `dist/`
`loko serve`	Preview server with live reload
`loko query`	Dependents, dependencies, paths, orphans, coupling
`loko export`	Compiled architecture as JSON or TOON
`loko mcp`	Start the MCP server for AI assistants
`loko completion`	Generate shell completion scripts

There are no loko init, loko new or loko watch commands; loko serve rebuilds on change, and loko build needs no d2 binary.

Without -p, loko uses the current directory.

loko validate

Compile the architecture and report every problem with position. --strict makes warnings fail the run too.

loko validate --strict -p examples/serverless

Exit codes are 0 clean, 1 errors, 2 warnings under --strict. There are exactly three, so a CI pipeline can branch on them.

loko fmt

Rewrite source files into canonical form. --check verifies without writing — for CI:

loko fmt --check -p examples/serverless

loko build

Render diagrams (D2 and SVG), markdown and an HTML site into dist/. No external d2 binary is needed.

loko build -p examples/serverless
loko build --format md   # markdown only (adds the SVG it embeds)

loko serve

Serve the site on http://127.0.0.1:8080 and rebuild on every change.

loko serve -p examples/serverless

loko query

Ask questions of the compiled model:

loko query dependents   <address> [--transitive]
loko query dependencies <address> [--transitive]
loko query path         <from> <to>
loko query orphans
loko query coupling     [--limit 20]

loko query dependents container.db             # what breaks if the database is down
loko query path person.customer container.db   # how a request reaches it
loko query orphans                             # elements with no relationships

--format json prints exactly what the MCP query tool returns; --format toon halves the size of tabular answers.

loko export

Write the compiled architecture as a byte-stable, machine-readable artifact:

loko export --format json
loko export --format toon

Flags: --format (json or toon) and --out (default stdout). Nothing is written when compilation reports errors. The same source always produces identical bytes — on any machine, in any file-system order — so a committed export is reviewable in a diff.

loko mcp

Start the MCP (Model Context Protocol) server for AI assistant integration.

Flag	Type	Default	Description
`--env`	string	`""`	Set an environment variable (`KEY=VALUE`) for the server

The server registers five tools: describe, query and validate read the compiled architecture; apply_edit and move edit the HCL source, compiling every change before anything is written. Tools write *.loko.hcl files and nothing else. See the MCP server page for setup.

loko completion

Generate a shell completion script (written to stdout). See loko completion --help.