Skip to content

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 .krs files in the browser while you edit, and keep them formatted and lint-clean.
  • Rendering in automation — turn .krs into 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:

Terminal window
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 ….

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.

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.

Terminal window
# from a directory with .krs files
karasu serve
# or point it at a directory and pick a port
karasu serve ./architecture --port 4000
karasu 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.

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:

Terminal window
# on the LAN, then open http://<this machine's address>:3000 elsewhere
karasu serve --host 0.0.0.0
# inside a container started with docker run -p 3000:3000
karasu serve /work --host 0.0.0.0

serve 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:

Terminal window
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).

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.

Terminal window
# Pipe to stdout and redirect to a file
karasu render index.krs > docs/arch.svg
# Write directly to a file
karasu render index.krs --output docs/arch.svg
# Render a single view
karasu 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 file
karasu render index.krs | svgo - -o docs/arch.svg
# Export to draw.io (mxGraph XML) as a layout escape hatch
karasu 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.

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:

Terminal window
# Translate a compose file and merge it into an existing deploy.krs
karasu translate --from compose docker-compose.yml | karasu apply deploy.krs

karasu 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.

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+)\)$.

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
Terminal window
# Copy every skill into ./.claude/skills
npx karasu skill install
# Copy one skill into the directory your agent reads skills from
npx karasu skill install karasu-author --dir .agents/skills

Each 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@karasu

© 2026 Hiroki Kondo · Licensed underApache-2.0

Built with Cloudflare