Using the karasu CLI
English(this file) · 日本語
The karasu CLI is the command-line side of karasu. It covers two main jobs:
- Authoring locally — preview your
.krsfiles in the browser while you edit, and keep them formatted and lint-clean. - Rendering in automation — turn
.krsinto SVG (or draw.io) from a script or CI job, so committed diagrams stay in sync with the model.
You do not need to install anything. The published package is karasu, so
every command can be run on demand with npx:
npx --yes karasu@latest <command> [args]Pin a version (karasu@0.1.0) in CI to avoid surprises. The rest of this page
drops the npx --yes prefix for brevity — karasu render … means
npx --yes karasu@latest render ….
When to reach for the CLI
Section titled “When to reach for the CLI”| You want to… | Use |
|---|---|
See your real .krs files update live as you edit |
karasu serve |
| Produce an SVG for docs, a README, or CI | karasu render |
Keep .krs / .krs.style formatted and valid |
fmt / tidy-style / lint-style |
Lift an existing system into .krs |
translate |
| Review what changed between two revisions | diff |
If you prefer a graphical, click-through experience instead of a preview that follows your editor, see Using the App.
karasu serve — live preview
Section titled “karasu serve — live preview”serve watches the .krs and .krs.style files in a directory and re-renders
them in your browser every time you save. Imports resolve as they do in
karasu render, so saving a file the open one imports redraws it too. You keep editing in your own editor; the preview
follows along. Reach for it during local authoring.
# from a directory with .krs fileskarasu serve
# or point it at a directory and pick a portkarasu serve ./architecture --port 4000karasu serve Directory : /path/to/architecture Preview : http://localhost:3000
Watching for .krs and .krs.style file changes...| Argument / option | Default | Meaning |
|---|---|---|
[dir] |
. |
Directory to watch for .krs files |
-p, --port <number> |
3000 |
Port the preview server listens on |
--host <addr> |
127.0.0.1 |
Address the preview server listens on. 0.0.0.0 listens on every IPv4 interface |
--allowed-host <name> |
(none) | Also answer the file API for requests whose Host names <name> (repeatable). .example.com also matches its subdomains |
Open the printed URL and edit — save, and the diagram re-renders with no manual
refresh. serve is preview-only; it embeds no editor. The
Using the App page covers the preview pane (views, navigation,
diagnostics, exports) and the URL-to-file mapping in detail.
Who can reach the preview
Section titled “Who can reach the preview”By default serve listens on 127.0.0.1 only, so other machines cannot reach
it. Both http://localhost:<port> and http://127.0.0.1:<port> open it.
To open it from another machine or from outside a container, listen on every interface:
# on the LAN, then open http://<this machine's address>:3000 elsewherekarasu serve --host 0.0.0.0
# inside a container started with docker run -p 3000:3000karasu serve /work --host 0.0.0.0serve then warns on startup: anyone who can reach that address can read the
.krs and .krs.style files in the served directory.
The file API (/api/*) answers only when the request’s Host is localhost,
a *.localhost name, or an IP address. This keeps a web page whose domain was
re-pointed at your machine (DNS rebinding) from reading your files. When you
open the preview through a name that is none of these, such as a Codespaces
forwarded port (*.app.github.dev) or a reverse proxy that passes its own DNS
name, add that name:
karasu serve --allowed-host my-codespace-3000.app.github.dev--allowed-host takes a bare host name: no port, scheme or path. A value
starting with . needs at least two labels (.example.com, not .com).
It is not access control. Anyone who can reach the proxy or the forwarded port
can read the served directory through it, so restrict who reaches it there
(keep the Codespaces port private, put authentication in front of the proxy).
karasu render — .krs → SVG
Section titled “karasu render — .krs → SVG”render converts a .krs file to an SVG (or draw.io XML) without a browser.
This is the command for automation: rendering a diagram in CI, embedding it
in docs, or committing an up-to-date SVG back to a repo. By default it writes to
stdout, so you redirect or pipe the result.
# Pipe to stdout and redirect to a filekarasu render index.krs > docs/arch.svg
# Write directly to a filekarasu render index.krs --output docs/arch.svg
# Render a single viewkarasu render index.krs --view deploy --output deploy.svg
# Use the light color theme (default: dark)karasu render index.krs --theme light --output arch-light.svg
# Optimize via a pipe — no temp filekarasu render index.krs | svgo - -o docs/arch.svg
# Export to draw.io (mxGraph XML) as a layout escape hatchkarasu render index.krs --format drawio --output arch.drawio| Option | Default | Meaning |
|---|---|---|
-o, --output <path> |
stdout | Write output to a file instead of stdout |
--view <type> |
all views bundled | One of system | deploy | org |
--format <format> |
svg |
svg, or drawio (one page per view + drill-down level) |
--theme <theme> |
dark |
dark | light — diagram color theme (svg only) |
--include-matrix |
off | Also write <output-stem>.matrix.svg (requires --format svg and --output) |
render resolves @import statements relative to the entry file, so for a
multi-file model you only point it at the top-level file. It exits with status
1 on a missing file or a parse error (warnings alone keep status 0), which
makes it safe to gate a CI step on. For a ready-made GitHub Actions workflow,
see GitHub Actions integration.
You can also pass a directory: karasu render docs/model renders
docs/model/index.krs, the same entry serve opens, and diagnostics name
docs/model/index.krs:<line>:<column>. A directory without an index.krs exits
1 and says so. check, matrix, coverage, team-dependencies and
subtree read a directory the same way.
Command reference
Section titled “Command reference”serve and render cover most day-to-day use. The CLI also includes commands
for keeping files tidy, lifting an existing system into .krs, and reviewing
changes. Run karasu <command> --help for the full option list and examples.
Two options mean the same on every command that takes them: -o, --output <path> writes to a file instead of stdout, and --format <format> picks one of
the formats the command’s row names.
| Command | What it does |
|---|---|
serve [dir] |
Serve .krs files from a directory with live preview |
render <file> |
Render a .krs file to SVG or draw.io |
check <file> |
Validate a .krs project without writing anything; exits 1 on any error. Runs the same compile as render, so a file that passes renders. Run it before fmt, which refuses unparseable files without saying where. Each diagnostic line carries its ID after the severity word (Warning[KRS041]: ...), which the diagnostics catalog lists; --format json prints the findings as one JSON document for scripts and agents |
matrix <file> |
Render a usecase × resource CRUD matrix (md / csv / svg). --service narrows the rows; --infra, --external and --no-external narrow the columns; --writes-only, --omit-empty and --no-totals trim the table |
team-dependencies <file> |
Derive which teams depend on which from owns × the logical edges, plus ownership that crosses containment (md / csv) |
coverage <file> |
Report each domain’s density to spot thinly modeled domains (md / json; --threshold sets the thin-score cut-off, 0..1) |
subtree <node-id> <file> |
Extract one node’s sub-tree as a standalone .krs (--with-ancestors keeps the full chain of ancestors) |
fmt [files...] |
Format .krs files in place (--check for CI, --stdin for pipes) |
tidy-style [files...] |
Tidy .krs.style files: merge duplicate rules, group properties (--check for CI, --stdin for pipes, --no-merge only reorders) |
lint-style [files...] |
Lint .krs.style property values against the schema (--stdin for pipes) |
translate <file> |
Translate an infra config or API spec into a .krs scaffold (--from compose | k8s | openapi | db | wrangler). --map points at a karasu.map.yaml (compose, k8s); --system wraps the emitted blocks in system <name> {} (openapi, db), names the system wrangler emits, and is ignored with a warning for compose and k8s; --service (openapi) and --database (db) name the service or database the spec becomes; --granularity picks resource or operation (openapi), aggregate or table (db); --emit-bindings adds usecase → resource bindings and --emit-crud-decoration also marks each operation’s CRUD verb (both only with --granularity resource for openapi or aggregate for db; other sources and granularities ignore them with a warning) |
apply <file> |
Apply piped .krs from stdin — replace a node by id, else append |
append <file> |
Append piped .krs from stdin as a new top-level block |
insert <parent-id> <file> |
Insert piped .krs from stdin as the last child of a node |
remove <node-id> <file> |
Remove a node by id from a .krs file in place |
diff <before> <after> |
Render a diff SVG between two .krs revisions (either side may be - for stdin; --view picks one view) |
capabilities |
List the commands, flags and deprecated names this CLI accepts (--json for skills and scripts; see below) |
skill install [name] |
Copy the karasu agent skills (default: all) into .claude/skills/ or --dir <path>, for agents that cannot install the Claude Code plugin (see below) |
skill path [name] |
Print where the installed CLI keeps a skill |
translate together with apply on a Unix pipe is how you fold changes from
the infrastructure side back into an existing model:
# Translate a compose file and merge it into an existing deploy.krskarasu translate --from compose docker-compose.yml | karasu apply deploy.krskarasu capabilities: what this CLI accepts
Section titled “karasu capabilities: what this CLI accepts”Skills and scripts that drive the CLI can ask it what it accepts instead of
assuming a version. karasu capabilities --json prints:
{ "schemaVersion": 1, "name": "karasu", "version": "0.8.0", "languageVersion": "1.0", "commands": [ { "name": "render", "arguments": ["<file>"], "options": [ { "flags": "-o, --output <path>", "long": "--output", "short": "-o", "takesValue": true } ] } ], "deprecations": [ { "kind": "flag", "name": "--out", "command": "render", "replacement": "--output", "since": "0.8.0", "removal": "1.0.0", "status": "deprecated" } ]}(The values above are illustrative.) A command with nested commands, such as
skill, lists them under subcommands in the same shape. schemaVersion
changes only when a field changes meaning or goes away; new fields may appear
without a bump. Without
--json the same information is printed as plain text.
Renamed and removed names
Section titled “Renamed and removed names”A command or flag that the CLI renames or retires keeps working under its old
name until the next major release (the CLI stays on 0.x until 1.0.0, and no
old name is removed before then). Using an old name runs the replacement and
prints one line on stderr:
karasu: deprecated: 'render --out' -> 'render --output' (since 0.8.0, removal 1.0.0)After the major release that removes it, the old name fails with exit status
1 and the same line, starting karasu: removed:, so the caller still learns
what to use instead. The line’s format is fixed and not translated, so an agent
can match it with
^karasu: (deprecated|removed): '(.+)' -> '(.+)' \(since (\S+), removal (\S+)\)$.
karasu skill: install the agent skills
Section titled “karasu skill: install the agent skills”The CLI ships the karasu agent skills (the
karasu-skills package) so any
agent that reads skill directories can use them, not only Claude Code:
| Skill | What it does |
|---|---|
karasu-author |
Builds and updates a model of your own system through conversation, one layer at a time, checking every change with karasu check |
reverse-architecture |
Reverse-engineers an existing repository into a model. See the guide |
# Copy every skill into ./.claude/skillsnpx karasu skill install
# Copy one skill into the directory your agent reads skills fromnpx karasu skill install karasu-author --dir .agents/skillsEach skill lands in <dir>/<name>/ with its SKILL.md and the bundled
reference docs. An installed skill is not overwritten unless you pass
--force, which replaces it with the copy from this CLI. karasu skill path <name> prints where the skill is, to point an agent at it without copying.
In Claude Code, install the plugin instead; it updates from the /plugin menu:
/plugin marketplace add kompiro/karasu/plugin install karasu@karasuSee also
Section titled “See also”- Using the App — the graphical preview/playground that shares
karasu serve’s preview pane. - GitHub Actions integration — rendering diagrams in CI
with
karasu render. - Core Concepts — the logical / physical / organizational dimensions the views render.
- Syntax reference and
Tags & annotations — the
.krslanguage the CLI parses.
© 2026 Hiroki Kondo · Licensed underApache-2.0