karasu CLI の使い方
English · 日本語(このファイル)
karasu CLI は karasu のコマンドライン側です。主な用途は 2 つあります。
- ローカルでの編集 — 編集しながら
.krsファイルをブラウザでプレビューし、 フォーマットと lint を保つ。 - 自動化でのレンダリング — スクリプトや CI から
.krsを SVG(または draw.io)に変換し、コミットした図をモデルと同期させ続ける。
インストールは不要です。公開パッケージ名は karasu なので、どのコマンドも
npx でその場で実行できます。
npx --yes karasu@latest <command> [args]CI では予期せぬ変化を避けるためバージョンを固定(karasu@0.1.0)してください。
以下では簡潔さのため npx --yes 接頭辞を省きます。karasu render … は
npx --yes karasu@latest render … を意味します。
どんなときに CLI を使うか
Section titled “どんなときに CLI を使うか”| やりたいこと | 使うコマンド |
|---|---|
編集に合わせて実ファイルの .krs をライブ更新したい |
karasu serve |
| ドキュメント・README・CI 用に SVG を生成したい | karasu render |
.krs / .krs.style をフォーマット・検証したい |
fmt / tidy-style / lint-style |
既存システムを .krs に取り込みたい |
translate |
| 2 つのリビジョン間の差分を確認したい | diff |
エディタに追従するプレビューではなく、クリックして操作するグラフィカルな体験が よければアプリの使い方を参照してください。
karasu serve — ライブプレビュー
Section titled “karasu serve — ライブプレビュー”serve はディレクトリ内の .krs と .krs.style を監視し、保存のたびにブラウザで
再描画します。import は karasu render と同じく解決され、開いているファイルが
import するファイルを保存しても再描画します。編集は普段使いのエディタで続けたまま、プレビューだけが追従します。
ローカルでの編集時に使います。
# .krs ファイルのあるディレクトリでkarasu serve
# ディレクトリとポートを指定する場合karasu serve ./architecture --port 4000karasu serve Directory : /path/to/architecture Preview : http://localhost:3000
Watching for .krs and .krs.style file changes...| 引数 / オプション | 既定値 | 意味 |
|---|---|---|
[dir] |
. |
.krs を監視するディレクトリ |
-p, --port <number> |
3000 |
プレビューサーバーが待ち受けるポート |
--host <addr> |
127.0.0.1 |
プレビューサーバーが待ち受けるアドレス。0.0.0.0 ですべての IPv4 インターフェースで待ち受ける |
--allowed-host <name> |
(なし) | Host が <name> の request にもファイル API を返す(繰り返し指定できる)。.example.com はサブドメインにも一致する |
表示された URL を開いて編集します。保存すると手動リロードなしで図が再描画され
ます。serve はプレビュー専用で、エディタは内蔵しません。プレビューペイン
(ビュー・ナビゲーション・診断・エクスポート)や URL とファイルの対応は
アプリの使い方で詳しく説明しています。
プレビューに届く範囲
Section titled “プレビューに届く範囲”既定では serve は 127.0.0.1 だけで待ち受けるので、別のマシンからは届きません。
http://localhost:<port> と http://127.0.0.1:<port> のどちらでも開けます。
別のマシンやコンテナの外から開くときは、すべてのインターフェースで待ち受けます。
# LAN で。別のマシンから http://<このマシンのアドレス>:3000 を開くkarasu serve --host 0.0.0.0
# docker run -p 3000:3000 で起動したコンテナの中でkarasu serve /work --host 0.0.0.0このとき serve は起動時に警告を出します。そのアドレスに届く人は誰でも、配信ディレクトリの
.krs と .krs.style を読めます。
ファイル API(/api/*)は、request の Host が localhost、*.localhost の名前、IP アドレスの
どれかのときだけ答えます。これで、ドメインをあなたのマシンに向け直した Web ページ(DNS rebinding)が
ファイルを読むことを防ぎます。これらのどれでもない名前でプレビューを開くとき(Codespaces の
forwarded port の *.app.github.dev や、自分の DNS 名を渡す reverse proxy など)は、その名前を足します。
karasu serve --allowed-host my-codespace-3000.app.github.dev--allowed-host にはホスト名だけを渡します。port・scheme・path は付けません。
. で始まる値は 2 ラベル以上にします(.com ではなく .example.com)。
--allowed-host はアクセス制御ではありません。proxy や forwarded port に届く人は誰でも、そこを通して配信
ディレクトリを読めます。届く人はそちらで絞ってください(Codespaces の port を private のままにする、
proxy の前に認証を置く、など)。
karasu render — .krs → SVG
Section titled “karasu render — .krs → SVG”render は ブラウザなしで .krs ファイルを SVG(または draw.io XML)に
変換します。CI での図のレンダリング、ドキュメントへの埋め込み、最新の SVG の
コミットなど、自動化のためのコマンドです。既定では stdout に書き出すため、
リダイレクトやパイプで結果を受け取ります。
# stdout にパイプしてファイルへリダイレクトkarasu render index.krs > docs/arch.svg
# ファイルへ直接書き込むkarasu render index.krs --output docs/arch.svg
# 単一ビューを描画するkarasu render index.krs --view deploy --output deploy.svg
# ライトテーマを使う(既定: dark)karasu render index.krs --theme light --output arch-light.svg
# パイプで最適化する — 一時ファイル不要karasu render index.krs | svgo - -o docs/arch.svg
# レイアウトの逃げ道として draw.io(mxGraph XML)へエクスポートkarasu render index.krs --format drawio --output arch.drawio| オプション | 既定値 | 意味 |
|---|---|---|
-o, --output <path> |
stdout | stdout の代わりにファイルへ出力する |
--view <type> |
全ビュー束ね | system | deploy | org のいずれか |
--format <format> |
svg |
svg、または drawio(ビュー / ドリルダウン階層ごとに 1 ページ) |
--theme <theme> |
dark |
dark | light — 図のカラーテーマ(svg のみ) |
--include-matrix |
off | <output-stem>.matrix.svg も書き出す(--format svg と --output が必要) |
render は @import をエントリファイルからの相対で解決するため、複数ファイルの
モデルでもトップレベルのファイルを指定するだけで済みます。ファイルが無い場合や
パースエラーの場合は終了コード 1 で終わります(警告のみなら 0)。そのため
CI ステップの成否判定に使えます。すぐ使える GitHub Actions ワークフローについて
はGitHub Actions 連携を参照してください。
ファイルの代わりにディレクトリを渡すこともできます。karasu render docs/model
は serve が開くのと同じエントリ docs/model/index.krs をレンダリングし、診断の
位置も docs/model/index.krs:<行>:<列> と表示します。index.krs が無いディレクトリ
を渡すと、そのことを伝えて終了コード 1 で終わります。check・matrix・
coverage・team-dependencies・subtree も同じようにディレクトリを受け付けます。
コマンドリファレンス
Section titled “コマンドリファレンス”serve と render で日常の用途はほぼカバーできます。CLI にはこのほか、ファイル
を整える・既存システムを .krs に取り込む・変更を確認するためのコマンドも
あります。各コマンドの全オプションと例は karasu <command> --help で確認でき
ます。
2 つのオプションは、受け付けるどのコマンドでも同じ意味です: -o, --output <path> は stdout の代わりにファイルへ書き出し、--format <format> はそのコマンドの
行に書いた形式から 1 つを選びます。
| コマンド | 機能 |
|---|---|
serve [dir] |
ディレクトリの .krs をライブプレビュー付きで配信 |
render <file> |
.krs を SVG または draw.io にレンダリング |
check <file> |
何も書き出さずに .krs プロジェクトを検証し、error が 1 つでもあれば終了コード 1。render と同じコンパイルを通すので、通ったファイルは描画できる。fmt より先に実行する(fmt はパースできないファイルを位置を示さずに拒否する)。診断の各行は severity の語の直後に ID(Warning[KRS041]: ...)を持ち、診断カタログで引ける。--format json はスクリプトやエージェント向けに、同じ診断を 1 つの JSON で出す |
matrix <file> |
ユースケース × リソースの CRUD マトリクスを出力(md / csv / svg)。--service で行を、--infra・--external・--no-external で列を絞り、--writes-only・--omit-empty・--no-totals で表を削る |
team-dependencies <file> |
owns × 論理エッジからチーム間の依存と、囲みを跨ぐ所有を導出して出力(md / csv) |
coverage <file> |
ドメインごとの密度を出し、モデルが薄いドメインを見つける(md / json。--threshold で薄さの閾値 0..1 を変える) |
subtree <node-id> <file> |
1 つのノードの部分木を単独の .krs として取り出す(--with-ancestors で祖先の連鎖をすべて残す) |
fmt [files...] |
.krs を in-place でフォーマット(CI 用 --check、パイプ用 --stdin) |
tidy-style [files...] |
.krs.style を整える: 重複ルールをまとめ、プロパティを軸ごとにグループ化(CI 用 --check、パイプ用 --stdin。--no-merge は並べ替えだけ) |
lint-style [files...] |
.krs.style のプロパティ値をスキーマに照らして lint(パイプ用 --stdin) |
translate <file> |
インフラ設定や API 仕様を .krs スキャフォールドに変換(--from compose | k8s | openapi | db | wrangler)。--map で karasu.map.yaml を指し(compose・k8s)、--system は出力したブロックを system <name> {} で包み(openapi・db)、wrangler が出す system の名前を上書きし、compose と k8s では警告を出して無視する。--service(openapi)・--database(db)で仕様から作る service / database に名前を付け、--granularity で粒度(openapi は resource / operation、db は aggregate / table)を選ぶ。--emit-bindings で usecase → resource の対応を足し、--emit-crud-decoration は各 operation に CRUD の動詞も付ける(どちらも openapi の --granularity resource と db の aggregate でだけ効き、ほかの変換元と粒度では警告を出して無視する) |
apply <file> |
stdin の .krs を適用 — 同 id のノードは置換、無ければ追記 |
append <file> |
stdin の .krs を新しいトップレベルブロックとして末尾に追記 |
insert <parent-id> <file> |
stdin の .krs を指定ノードの最後の子として挿入 |
remove <node-id> <file> |
指定 id のノードを .krs から in-place で削除 |
diff <before> <after> |
2 つの .krs リビジョン間の差分 SVG を描画(どちらの側も - で stdin 可。--view で 1 つのビューを選ぶ) |
capabilities |
この CLI が受け付けるコマンド・フラグと、廃止した名前を一覧(skill やスクリプトからは --json。下記) |
skill install [name] |
karasu の agent skill(省略時はすべて)を .claude/skills/ か --dir <path> にコピー。Claude Code の plugin を入れられないエージェント向け(下記) |
skill path [name] |
インストール済み CLI が skill を置いている場所を表示 |
translate と Unix パイプの apply を組み合わせると、インフラ側の変更を既存の
モデルに取り込めます。
# compose ファイルを変換して既存の deploy.krs にマージするkarasu translate --from compose docker-compose.yml | karasu apply deploy.krskarasu capabilities: この CLI が受け付けるもの
Section titled “karasu capabilities: この CLI が受け付けるもの”CLI を呼ぶ skill やスクリプトは、版を決め打ちせずに、受け付けるものを CLI に
問い合わせられます。karasu capabilities --json の出力:
{ "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" } ]}(値は例です。)skill のように下にコマンドを持つコマンドは、それを同じ形で
subcommands に並べます。schemaVersion が変わるのは、フィールドの意味が変わるか無くなる
ときだけです。フィールドは版を上げずに増えることがあります。--json を付けない
と、同じ内容をプレーンテキストで出力します。
名前の変更と削除
Section titled “名前の変更と削除”CLI が名前を変えた・廃止したコマンドやフラグは、次の major リリースまで古い名前
でも動きます(CLI は 1.0.0 まで 0.x で、それまでは古い名前を削除しません)。
古い名前で呼ぶと代わりが実行され、stderr に 1 行出ます:
karasu: deprecated: 'render --out' -> 'render --output' (since 0.8.0, removal 1.0.0)古い名前を削除する major リリース以降は、同じ形式で karasu: removed: から
始まる行を出して終了コード 1 で失敗します。呼び出し側は何を使えばよいかを
引き続き知ることができます。この行の形式は固定で翻訳しないので、エージェントは
^karasu: (deprecated|removed): '(.+)' -> '(.+)' \(since (\S+), removal (\S+)\)$
で照合できます。
karasu skill: agent skill を入れる
Section titled “karasu skill: agent skill を入れる”CLI は karasu の agent skill(karasu-skills
パッケージ)を同梱しているので、Claude Code に限らず、skill のディレクトリを読む
エージェントならどれでも使えます:
| Skill | 何をするか |
|---|---|
karasu-author |
自分のシステムのモデルを、会話しながら 1 層ずつ作り・更新する。変更のたびに karasu check で検証する |
reverse-architecture |
既存のリポジトリをリバースエンジニアリングしてモデルにする。ガイドを参照 |
# すべての skill を ./.claude/skills にコピーnpx karasu skill install
# 1 つの skill を、エージェントが skill を読むディレクトリにコピーnpx karasu skill install karasu-author --dir .agents/skillsskill は <dir>/<name>/ に SKILL.md と同梱の reference と一緒に入ります。
インストール済みの skill は上書きしません。--force を付けると、この CLI が
持つ版で置き換えます。コピーせずにエージェントに場所を教えたいときは
karasu skill path <name> で場所を表示できます。
Claude Code では代わりに plugin を入れてください。/plugin メニューから更新できます:
/plugin marketplace add kompiro/karasu/plugin install karasu@karasu- アプリの使い方 —
karasu serveとプレビューペインを共有する グラフィカルなプレビュー / プレイグラウンド。 - GitHub Actions 連携 —
karasu renderで CI 上に図を 生成する。 - コアコンセプト — 各ビューが描画する論理 / 物理 / 組織の 3 次元。
- 構文リファレンス と
タグ・アノテーション — CLI がパースする
.krs言語。
© 2026 Hiroki Kondo · Licensed underApache-2.0