Quickstart

Install

Homebrew (macOS and Linux, recommended)

brew install --cask madstone-tech/tap/loko
loko --version

From Go

go install github.com/madstone-tech/loko@latest     # needs Go 1.27 or later

Docker

Run the image without installing anything:

docker run --rm -v "$PWD:/workspace" ghcr.io/madstone-tech/loko validate

Release archives for Linux, macOS and Windows are on the releases page.

Nothing else is needed for rendering: diagrams render inside loko, so there is no d2 binary to install.

Write an architecture

Create arch.loko.hcl:

project "acme-payments" {
  description  = "Payment processing platform"
  loko_version = "~> 1.0"
}

person "customer" {
  description = "Pays for orders"

  uses "checkout" {
    target      = container.api
    description = "Pays with a card"
    technology  = "HTTPS"
  }
}

system "payments" {
  description = "Authorization, capture, settlement"
  owner       = "platform-team"
}

container "api" {
  system     = system.payments
  title      = "Payments API"
  technology = "AWS Lambda (Go)"
  shape      = "function"

  uses "orders" {
    target      = container.orders_db
    description = "Reads and writes orders"
  }

  uses "settle" {
    target      = container.settlements
    description = "Queues captured payments"
    kind        = "async"
  }
}

container "orders_db" {
  system     = system.payments
  technology = "Aurora PostgreSQL"
  shape      = "database"
}

container "settlements" {
  system     = system.payments
  technology = "Amazon SQS"
  shape      = "queue"
}

Check it, draw it, ask it

loko validate                              # errors and warnings, with positions
loko build                                 # diagrams, markdown and a site in ./dist
loko serve                                 # preview at http://localhost:8080, live reload
loko query dependents container.orders_db  # who breaks if the database is down?
loko query path person.customer container.orders_db   # how a request reaches it
loko query orphans                         # elements with no relationships
loko export --format json                  # the compiled model, for programs and CI

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

Common commands

Command	Description
`loko validate`	Compile and report diagnostics
`loko fmt`	Canonical formatting (`--check` for CI)
`loko query`	Dependents, dependencies, paths, orphans, coupling
`loko export`	Compiled architecture as JSON or TOON
`loko build`	Render diagrams, markdown and a site into `dist/`
`loko build --format md`	Markdown only (adds the SVG it embeds)
`loko serve`	Preview server with live reload
`loko mcp`	Start MCP server

Use loko --help for general help, and loko build --help or loko serve --help for command-specific help. The full reference is on the CLI reference page.