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:

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

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

serve watches the .krs files in a directory and re-renders them in your browser every time you save. You keep editing in your own editor; the preview follows along. Reach for it during local authoring.

# 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 file changes...

Argument / option	Default	Meaning
[dir]	.	Directory to watch for .krs files
-p, --port <number>	3000	Port the preview server listens on

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.

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

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.

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
matrix <file>	Render a usecase × resource CRUD matrix (md / csv / svg)
team-dependencies <file>	Derive which teams depend on which from owns × the logical edges, plus ownership that crosses containment (md / csv)
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
lint-style [files...]	Lint .krs.style property values against the schema
translate <file>	Translate an infra config or API spec into a .krs scaffold (--from compose | k8s | openapi | db)
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)
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.krs
karasu translate --from compose docker-compose.yml | karasu apply deploy.krs

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

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

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

# 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

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 .krs language the CLI parses.