Codatum CLI

Appearance

cdm notebook ​

cdm notebook サブコマンドで、ノートブックファイルの取得・反映・検証・プレビューなどを行います。

cdm notebook <subcommand> [arguments] [options]
サブコマンド用途
notebook cloneサーバからノートブックを新規取得
notebook pull既存ノートブックファイルの最新化
notebook diffサーバとの差分確認
notebook pushノートブックの書き戻し
notebook previewノートブックのプレビュー
notebook validateノートブックファイルの検証
notebook formatノートブックファイルのフォーマット
notebook stripノートブックファイルからジョブ実行情報を削除
notebook build-sqlノートブックファイル内のSQLのビルド

サブコマンド共通事項 ​

ワークスペースとの整合性確認 ​

ノートブックファイルを対象とした操作では、ノートブックファイルのフロントマターで指定されたワークスペースID（workspace_id）と、利用中の profile のワークスペースIDが一致しているかを検証します。

  • ワークスペースIDが一致しない場合、コマンドは exit 1 で終了します
  • ディレクトリに対する操作の場合、ディレクトリ配下のすべてのノートブックファイルに対して整合性を確認します

ノートブックの識別 ​

ノートブックファイルを対象とした操作では、ノートブックファイルのフロントマターで指定されたノートブックID（id）を用いて、サーバ側のノートブックを特定します。

ノートブックの新規取得 ​

cdm notebook clone <notebookId|url>
  -o, --output <path>   出力先（ファイルパス または ディレクトリ）
  --stdout              標準出力に出力（--output と排他）
  -y, --yes             既存ファイルがある場合の確認プロンプトをスキップ
  --profile <name>      利用する profile を指定

サーバ上のノートブックをローカルに保存します。

ノートブックの指定方法 ​

第1引数の <notebookId|url> には、以下のいずれかを指定してください。

  • notebookId （24文字の16進数）: 例 671ef14b0d08cf6c657df7da
  • URL: Codatum のノートブックページのURL
    • 形式: https://app.codatum.com/workspace/<wsId>/notebook/<notebookId>/<pageId>
    • URL 内の <wsId> は、利用中の profile のワークスペースと一致する必要があります

出力先 ​

  • --output で出力先を指定できます
    • ファイルパスを指定した場合、そのパスに書き込みます
      • 拡張子を省略した場合は .cnb.md を付与します（例: notebooks/sales → notebooks/sales.cnb.md）。
    • ディレクトリを指定した場合、ディレクトリ内にファイルを生成します
      • ファイル名はノートブック名から自動生成されます
    • 書き込み先に既存のファイルがある場合、確認プロンプトが表示されます
      • --yes を指定することで、確認をスキップできます
    • 中間ディレクトリは必要に応じて自動作成します
  • --stdout を指定した場合、マークダウンを標準出力に出力します
  • --ouput, --stdout のいずれも指定のない場合は、 --output ./ として処理します

利用例 ​

bash
# URL コピペで一発取得（カレントディレクトリに自動命名）
cdm notebook clone https://app.codatum.com/workspace/.../notebook/.../...

# notebooks/ ディレクトリに自動命名で保存
cdm notebook clone 671ef14b0d08cf6c657df7da -o notebooks/

# ファイル名まで明示
cdm notebook clone 671ef14b0d08cf6c657df7da -o notebooks/sales.cnb.md

# 標準出力
cdm notebook clone 671ef14b0d08cf6c657df7da --stdout > sales.cnb.md

ノートブックの最新化 ​

cdm notebook pull <target>
  -y, --yes             確認プロンプトをスキップして反映
  --profile <name>      利用する profile を指定

サーバから最新状態を取得して、ローカルのノートブックファイルを上書きします。

  • <target> にディレクトリを指定した場合、配下の *.cnb.md を再帰的に処理します
  • <target> にファイルを指定した場合、そのファイルのみを処理します
  • 変更がある場合、書き込み前に確認プロンプトが表示されます
    • --yes を指定することで、確認をスキップできます
    • 差分を確認したい場合は、cdm notebook diff を実行してください

出力例 ​

/notebooks/sales.cnb.md         changed
/notebooks/users.cnb.md         unchanged

2 files processed: 1 changed, 1 unchanged

? Pull these changes from the server? (y/N)

利用例 ​

bash
# 確認しつつ反映
cdm notebook pull notebooks/

# CI 等で確認なしに反映
cdm notebook pull notebooks/ --yes

サーバとの差分確認 ​

cdm notebook diff <file>
  --exit-code           差分がある場合に exit 2 を返す
  --profile <name>      利用する profile を指定

指定したノートブックファイルをサーバに push した場合に発生する差分を出力します。

  • <file> にはノートブックファイルを指定してください
  • 単純な文字列の差分ではなく、サーバ側で実際にノートブックの統合処理を行った結果としての差分を出力します
  • サーバへの送信前にノートブックファイルの検証を行い、エラーが見つかった場合は exit 1 で終了します
  • --exit-code を指定した場合、差分がある場合は exit 2 で終了します

出力例 ​

差分がある場合:

diff
--- notebooks/sales.cnb.md (server: before)
+++ notebooks/sales.cnb.md (server: after)
@@ -45,7 +45,7 @@
-SELECT * FROM users WHERE created_at > '2024-01-01'
+SELECT * FROM users WHERE created_at > '2025-01-01'

利用例 ​

bash
# 差分確認
cdm notebook diff notebooks/sales.cnb.md

# CI レビュー用に diff をファイルへ保存
cdm notebook diff notebooks/sales.cnb.md > review.patch

# CI で変更検知（変更があれば exit 2）
cdm notebook diff notebooks/sales.cnb.md --exit-code

ノートブックの書き戻し ​

cdm notebook push <target>
  -y, --yes             確認プロンプトをスキップして反映
  --profile <name>      利用する profile を指定

指定したノートブックファイルの内容をサーバに送信し、サーバ上のノートブックに反映します。

  • <target> にディレクトリを指定した場合、配下の *.cnb.md を再帰的に処理します
  • <target> にファイルを指定した場合、そのファイルのみを処理します
  • サーバへの送信前にノートブックファイルの検証を行い、検証エラーが見つかった場合は exit 1 で終了します
    • 複数のファイルを対象とする場合、すべてのファイルを検証し終えてから、エラーをまとめて報告します。
  • この処理によりサーバのノートブックが更新される場合、書き込み前に確認プロンプトが表示されます
    • --yes を指定することで、確認をスキップできます
    • 詳細な差分を事前に確認したい場合は、別途 diff を実行してください。

出力例 ​

/notebooks/sales.cnb.md         changed
/notebooks/users.cnb.md         unchanged

2 files processed: 1 changed, 1 unchanged

? Push these changes to the server? (y/N)

利用例 ​

bash
# 確認しつつ反映
cdm notebook push notebooks/

# 事前に個別ファイルの差分を確認してから反映
cdm notebook diff notebooks/sales.cnb.md
cdm notebook push notebooks/

# CI で確認なしに反映
cdm notebook push notebooks/ --yes

ノートブックのプレビュー ​

cdm notebook preview <file>
  -p, --port <n>      ファイル同期用の WebSocket ポート番号（既定: 8743）
  -d, --debug         同期・書き込みの詳細ログを出力
  --profile <name>    利用する profile を指定

Codatum の Web サービスをブラウザ経由で起動します。

  • 既定ポート（8743）または --port で指定したポートが使用中の場合、そこから順に空きポートを探索して利用します
  • <file> にはノートブックファイルを指定してください
  • ブラウザでは、指定したノートブックファイルのプレビュー画面を開きます
  • プレビュー中は、表示対象のノートブックファイルに対して、以下の処理が自動的に適用されます。
    • ファイルの更新をポーリングにより監視し、自動でプレビューを更新します
    • format によるフォーマット処理が自動的に適用され、自動修復可能なエラーは自動的に修復されます
    • プレビュー内でユーザの行った操作（クエリの実行や、チャートの追加・編集等）が自動的にファイルに反映されます

注意事項 ​

  • エディタによりノートブックファイルを編集しつつ、プレビューすることを想定していますが、エディタの環境や設定により、期待しない動作をする可能性があります
  • エディタからの保存時に書き込みの競合が頻発する場合、以下の設定をご確認ください
    • エディタの保存時の自動フォーマット機能（formatOnSave）が有効な場合、プレビューからの変更と競合するため、必ず無効にしてください
    • 同じエディタプロセス内で大量のファイルを監視している場合、ファイル監視イベントの遅延によりエディタに更新が反映されず、競合が発生しやすくなります
      • 大量のファイルを監視するエディタプロセスを終了してからファイルを編集すると、競合が発生しにくくなります

ノートブックの検証 ​

cdm notebook validate <target>
  --profile <name>    利用する profile を指定

対象のノートブックファイルのスキーマ・構文を検証します。ファイルは書き換えません。

  • <target> にディレクトリを指定した場合、配下の *.cnb.md を再帰的に処理します
  • <target> にファイルを指定した場合、そのファイルのみを処理します
  • 検証エラーが見つかった場合、exit 1 で終了します
    • 複数のファイルを対象とする場合、すべてのファイルを検証し終えてから、エラーをまとめて報告します
    • 自動修復可能なエラーも検証エラーとして扱われるため、formatを実行することでエラーを解消できる場合があります

ノートブックのフォーマット ​

cdm notebook format <target>
  --check             ファイルを書き換えず、フォーマットが必要なファイルを表示して終了
                      （差分あり → exit 1、CI用）
  --profile <name>    利用する profile を指定

対象の *.cnb.md ファイルをフォーマットします。

  • <target> にディレクトリを指定した場合、配下の *.cnb.md を再帰的に処理します
  • <target> にファイルを指定した場合、そのファイルのみを処理します
  • 処理内でファイルの検証も同時に行い、自動修復可能なエラーは自動修復し、自動修復不可能なエラーが見つかった場合、exit 1 で終了します。

自動修復について ​

  • 検証エラーのうち以下に示すような一部のエラーは format コマンドにより自動的に修復されます。
    • ページ属性の指定漏れ
    • 各属性における id の指定漏れ

ジョブ実行情報の削除 ​

cdm notebook strip <target>
  --profile <name>    利用する profile を指定

対象のノートブックファイルから、ノートブック実行に紐づくジョブ実行情報（ジョブID、エラー、実行結果ID等）を削除します。

  • <target> にディレクトリを指定した場合、配下の *.cnb.md を再帰的に処理します
  • <target> にファイルを指定した場合、そのファイルのみを処理します
  • 処理内でファイルの検証も同時に行い、エラーが見つかった場合、exit 1 で終了します。
    • 自動修復可能なエラーも検証エラーとして扱われるため、対象と同じパスを指定して cdm notebook format を実行することで解消できる場合があります。

SQLのビルド ​

cdm notebook build-sql <file>
  -k, --key <key>       特定の SQL のみ出力（省略時は対象の SQL を全て出力）
  -f, --format <fmt>    出力形式: text | json（既定: text）
  --profile <name>      利用する profile を指定

対象のノートブックファイル内に含まれる SQLを、バインド値などを解決した実行可能な形にビルドして出力します。ファイルは書き換えません。

  • <file> にはノートブックファイルを指定してください
  • ワークスペースのコネクション一覧を参照して SQL をビルドします
  • --key を省略した場合、ファイル内の対象 SQL を全て出力します。
    • SQLブロックを指定する場合は pageId:${pageId}/sqlId:${sqlId} 形式で指定してください。
  • --key で指定したキーが存在しない場合、エラーを出力して exit 1 で終了します。
  • 処理内でファイルの検証も同時に行い、エラーが見つかった場合、exit 1 で終了します。

出力形式 ​

text（既定） ​

SQL をそのまま出力します。

  • --key を指定した場合、該当の SQL 文のみを出力します。
  • --key を省略した場合、各 SQL の直前に -- @cnb-sql <key> 形式のコメント行を区切りとして挿入し、SQL 間を空行で区切って連結します。
    • SQL 末尾にセミコロンは付与しません。
    • 個別の SQL に分割する場合は、-- @cnb-sql をマーカーとして split してください。

出力例（全件出力時）:

sql
-- @cnb-sql pageId:page1/sqlId:q1
SELECT * FROM users WHERE created_at > '2025-01-01'

-- @cnb-sql pageId:page1/sqlId:q2
SELECT COUNT(*) FROM orders WHERE status = 'completed'

json ​

キーと SQL のペアの配列を JSON で出力します。

出力例:

json
[
  { "key": "pageId:page1/sqlId:q1", "sql": "SELECT * FROM users WHERE created_at > '2025-01-01'" },
  { "key": "pageId:page1/sqlId:q2", "sql": "SELECT COUNT(*) FROM orders WHERE status = 'completed'" }
]