Codatum CLI

Appearance

はじめに ​

cdm とは ​

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

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

  • ノートブック編集: ノートブックをマークダウンファイル（.cnb.md）として取得・編集・反映する
  • データ参照: ワークスペース内のコネクション一覧やテーブルカタログを検索する
  • カタログ整備: テーブル・カラムの説明やタグを .cann.yaml / .ctag.yaml として管理し、サーバのカタログと同期する
  • 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）のコネクションを登録

必要な環境 ​

  • ターミナル（macOS / Linux では curl、Windows では PowerShell 5.1 以降）
  • AIエージェント（Cursor / Claude Code / Codex / Gemini CLI など）

クイックスタート ​

ここでは、ノートブックを取得して編集・反映するまでの流れを説明します。結果を見ながら対話的に作り込みたい場合は、後述の プレビューでインタラクティブに編集する も利用できます。

1. インストール ​

インストーラは OS と CPU アーキテクチャを自動判定して最新版の cdm を配置し、PATH の設定も自動で行います（詳細は インストール を参照）。

macOS / Linux:

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

WARNING

macOS / Linux では、追記した PATH 設定はすぐには反映されません。新しいターミナルを開くか、インストーラが案内する source コマンドを実行してから cdm を利用してください。

Windows（PowerShell）:

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

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

sh
cdm --version

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

sh
cdm update

2. 認証（profile の登録） ​

cdm auth login を実行すると CLI がブラウザを開くので、承認画面でワークスペース・profile 名・有効期限・権限を指定して「承認」を押すと、PAT が発行されて CLI に取り込まれます。

sh
cdm auth login

発行済みの PAT を使う場合など、他の登録方法は cdm auth を参照してください。

3. AIエージェントのセットアップ（任意） ​

AIエージェントに編集を任せたい場合は、cdm skill install で、エージェントに cdm の使い方を伝える SKILL.md を配置します。詳しくは AIエージェントのセットアップ を参照してください（手動編集するだけの場合は不要です）。

sh
cdm skill install   # 対話でエージェントを選んで配置

4. ノートブックの作成 ​

新しいノートブックを作る場合は、作成先のフォルダを cdm notebook folder list と cdm notebook folder info で確認してから、 cdm notebook create で作成します。

sh
# 作成先の候補となるフォルダを確認
cdm notebook folder list

# 編集権限があるフォルダかを確認（ノートブックの新規作成には write 権限が必要）
cdm notebook folder info WORKSPACE

# ワークスペースのルートフォルダに作成する場合
cdm notebook create WORKSPACE

# 特定のフォルダに、ノートブック名と出力先を指定して作成する場合
cdm notebook create 67955fa3c1834fdc34705bf8 -n "My Notebook" -o notebooks/my-notebook.cnb.md

既存のノートブックを編集する場合 ​

新しいノートブックを作成せずに、既存のノートブックを編集する場合は、cdm notebook clone でローカルに取得します。

sh
# URL から取得（カレントディレクトリに自動命名で保存）
cdm notebook clone https://app.codatum.com/workspace/xxx/notebook/yyy/zzz

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

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

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

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

sh
cdm connection list   # コネクション一覧を取得

6. 検証とフォーマット ​

編集後、スキーマ・構文の検証と整形を行います。検証のみの場合は cdm notebook validate を、整形も行う場合は cdm notebook format を実行します。

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

7. ノートブックの実行 ​

ノートブック内のSQLを cdm notebook run で一括実行し、結果をファイルに反映します。 cdm notebook run は実行結果のキャッシュを利用できるため、SQLに変更があったものだけが実行されます。最新のデータで実行したい場合は --refresh オプションを指定します。

sh
cdm notebook build-sql notebooks/my-notebook.cnb.md  # 任意: 実行されるSQLを確認
cdm notebook run notebooks/my-notebook.cnb.md            # SQLの一括実行
cdm notebook run notebooks/my-notebook.cnb.md --refresh  # 最新のデータで実行

8. ノートブックの仕上げ確認 ​

ノートブック内のページやチャートを cdm notebook render page / cdm notebook render chart で画像出力（スクリーンショット）して仕上がりを確認します。

sh
cdm notebook render page notebooks/my-notebook.cnb.md  # 全ページを PNG で出力
cdm notebook render chart notebooks/my-notebook.cnb.md --key pageId:6a17a2ba/chartId:6a18d401  # チャートを PNG で出力

9. サーバへの反映 ​

問題がなければ、変更をサーバに反映します。事前に差分を確認したい場合は cdm notebook diff を実行します。

sh
cdm notebook diff notebooks/my-notebook.cnb.md    # 任意: 反映される差分を確認
cdm notebook push notebooks/my-notebook.cnb.md    # サーバへ書き戻し

プレビューでインタラクティブに編集する ​

cdm notebook preview を使ってブラウザのプレビューを開くことで、SQLの実行結果やチャートを見ながら編集することができます。

ブラウザによるプレビューは単なるビューアではなく、ローカルの .cnb.md ファイルとブラウザを双方向同期するライブセッションです。起動している間は、ファイルへの編集がブラウザに即座に反映され、ブラウザ上での操作もファイルへ書き戻されます。

sh
cdm notebook preview notebooks/my-notebook.cnb.md

プレビューの起動中は、ブラウザ側から次の操作が行えます。

そのため、プレビューを使う場合は、クイックスタートの 6 〜 9 はユーザがブラウザから直接操作することができます。

次のステップ ​

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

CLI の全コマンドを理解する ​

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

SQL とパラメータを書く ​

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

チャートを定義する ​

ダッシュボードを作る ​

分析コンテキストを整える ​

AIエージェントに精度よく分析させるために、テーブル・カラムの意味や扱いをカタログ・ノートブックに整理します。

Codatum CLI AIエージェントのための分析環境

© Codatum Inc.