はじめに

cdm とは

cdm は、Codatum の機能をターミナルから操作するための CLI ツールです。 Codatum の Web サービスを補完し、ローカル環境やCI、AIエージェントから Codatum を扱えるようにすることを目的としています。

提供している機能は次の通りです。

• ノートブック編集: ノートブックをマークダウンファイル（.cnb.md）として取得・編集・反映する
• データ参照: ワークスペース内のコネクション一覧やテーブルカタログを検索する
• SQL 実行: コネクションに対して SQL を実行・検証する
• ドキュメント取得: Codatum 自身のドキュメントを CLI から取得する（AIエージェントが参照する用途を想定）
• 認証管理: PAT（パーソナルアクセストークン）を profile として管理し、複数ワークスペースを切り替える

各機能の詳細は cdm コマンドを参照してください。 本ページでは、主要なユースケースであるノートブックの編集を例に、セットアップから反映までの一連の流れを説明します。

マークダウン版ノートブックについて

.cnb.md の拡張子を持つマークダウンファイルをノートブックファイルと呼びます。 Web版ノートブックと相互変換可能なフォーマットで、以下の特徴があります。

• Git等でのバージョン管理が可能: テキスト形式なので diff やレビューが行いやすい
• AIエージェントによる編集を想定: 仕様はドキュメント化されており、エージェントは cdm doc で必要な情報を取得しながら編集できる
• CLI と Web の双方向同期: cdm notebook preview で、ローカル編集とブラウザ操作を同期できる

フォーマットの詳細は ノートブックファイルを参照してください。

事前準備

Codatum アカウントとワークスペース

cdm は Codatum の Web サービスと連携して動作するため、事前に以下を準備してください。

1. Codatum にサインアップ
2. ワークスペースを作成
3. データウェアハウス（BigQuery / Snowflake / Databricks / Redshift）のコネクションを登録
4. 編集対象のノートブックを Web 版で作成する（既存のノートブックでも可）

必要な環境

• ターミナル（macOS / Linux では curl、Windows では PowerShell 5.1 以降）
• AIエディタ（Cursor / Claude Code を推奨）

クイックスタート

ここでは、ノートブックを取得して編集・反映するまでの最小フローを示します。

1. インストール

macOS / Linux:

curl -fsSL https://cli-dist.codatum.com/install.sh | sh

Windows（PowerShell）:

irm https://cli-dist.codatum.com/install.ps1 | iex

インストーラは OS と CPU アーキテクチャを自動判定し、最新版の cdm をダウンロードして配置します。

• macOS / Linux: ~/.local/bin/cdm に配置します。~/.local/bin が PATH に含まれていない場合、インストーラがシェル設定への追記コマンドを表示するので、それに従って追記後、新しいターミナルを開いてください。
• Windows: %LOCALAPPDATA%\Programs\cdm\bin\cdm.exe に配置し、ユーザー PATH に追加します。実行したターミナルでは即座に cdm を使えますが、他のターミナルや IDE では新しいセッションを開始してから利用してください。

インストールが成功したか、バージョンを表示して確認します。

cdm --version

アップデート

すでに cdm をインストール済みの場合は、次のコマンドで最新化できます。

cdm update

2. 認証（profile の登録）

Codatum の Web サービスで PAT を発行し、cdm auth login で profile として登録します。

1. Codatum にログイン
2. アカウント設定 → パーソナルアクセストークン で PAT を発行
3. ターミナルで以下を実行し、対話プロンプトに PAT を入力

cdm auth login

詳細やオプションは cdm auth を参照してください。

3. ノートブックの取得（clone）

編集するノートブックを cdm notebook clone コマンドでローカルに保存します。

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

# notebooks/ ディレクトリに自動命名で保存
cdm notebook clone <notebookId|url> -o notebooks/

# ファイル名まで明示
cdm notebook clone <notebookId|url> -o notebooks/my-notebook.cnb.md

サーバ側で変更があった場合は、編集前に cdm notebook pull でローカルのノートブックファイルを最新化できます。

4. ノートブックファイルの編集

取得したファイルをエディタで開き、編集します。

• SQLブロックの作成時に必要なコネクションIDは、cdm connection list で確認できます
• 編集中にブラウザでプレビューを表示したい場合は、cdm notebook preview でブラウザを起動します
  • プレビューを利用する場合は、エディタの formatOnSave は無効にしてください（プレビューからの書き込みと競合するため）

cdm connection list                                # コネクション一覧を取得
cdm notebook preview notebooks/my-notebook.cnb.md  # 任意: プレビューを表示

5. 検証とフォーマット

編集後、スキーマ・構文の検証と整形を行います。

cdm notebook validate notebooks/my-notebook.cnb.md   # 検証のみ
cdm notebook format notebooks/my-notebook.cnb.md     # 自動修復 + 検証 + 整形

6. サーバへの反映（push）

問題がなければ、変更をサーバに反映します。

• 事前に差分を確認したい場合は cdm notebook diff を実行します

cdm notebook diff notebooks/my-notebook.cnb.md    # 任意: 反映される差分を確認
cdm notebook push notebooks/my-notebook.cnb.md

AIエディタとの連携

マークダウン版ノートブックは、AIエディタ／AIエージェントから編集することを想定して設計されています。

AIエディタから cdm コマンドを実行することで、エージェントは以下を取得しながら編集を進められます。

• 編集対象のフォーマット仕様（cdm doc 経由）
• 利用可能なコネクション一覧（cdm connection list）
• テーブルとカラムの実体（cdm catalog search-tables）
• 編集中のSQLの妥当性確認（cdm sql dry-run / cdm sql run）

エディタごとに設定方法が異なります。

• Cursor で連携する
• Claude Code で連携する

AIエージェントが *.cnb.md ファイルを編集する場合は、AIエージェント向けガイドを参照してください（エージェント本体に読ませる前提で書かれています）。

次のステップ

目的別に、次に読むべきドキュメントを示します。

ノートブックの構造を理解する

• ノートブックファイル — .cnb.md ファイルの全体構成
• ドキュメントページ — マークダウンとSQLブロックを記述するページ
• グリッドページ — チャートをダッシュボードとしてレイアウトするページ

SQL とパラメータを書く

• SQLブロック — SQLの定義、プレースホルダ、参照の仕組み
• パラメータ — 動的なダッシュボードを作るためのパラメータ定義

チャートを定義する

• チャート設定 — チャート設定の全体像と種類
• ディメンションとメトリクス — チャートのデータモデリングの基本

ダッシュボードを作る

• グリッドページ — グリッドレイアウトの記述方法
• クロスフィルタ — チャート間の絞り込みを連動させる機能

CLI の他の機能

• cdm コマンド — 全サブコマンドの一覧
• cdm update — CLI 本体の更新
• cdm sql — SQL の実行・検証
• cdm catalog — テーブルカタログの検索