コンテンツにスキップ

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 … を意味します。

やりたいこと 使うコマンド
編集に合わせて実ファイルの .krs をライブ更新したい karasu serve
ドキュメント・README・CI 用に SVG を生成したい karasu render
.krs / .krs.style をフォーマット・検証したい fmt / tidy-style / lint-style
既存システムを .krs に取り込みたい translate
2 つのリビジョン間の差分を確認したい diff

エディタに追従するプレビューではなく、クリックして操作するグラフィカルな体験が よければアプリの使い方を参照してください。

serve はディレクトリ内の .krs と .krs.style を監視し、保存のたびにブラウザで 再描画します。import は karasu render と同じく解決され、開いているファイルが import するファイルを保存しても再描画します。編集は普段使いのエディタで続けたまま、プレビューだけが追従します。 ローカルでの編集時に使います。

ターミナルウィンドウ
# .krs ファイルのあるディレクトリで
karasu serve
# ディレクトリとポートを指定する場合
karasu serve ./architecture --port 4000
karasu 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 とファイルの対応は アプリの使い方で詳しく説明しています。

既定では 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 の前に認証を置く、など)。

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 も同じようにディレクトリを受け付けます。

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

karasu 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 を付けない と、同じ内容をプレーンテキストで出力します。

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+)\)$ で照合できます。

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/skills

skill は <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

© 2026 Hiroki Kondo · Licensed underApache-2.0

Built with Cloudflare