Codatum CLI

Appearance

Cursor ​

Cursor から cdm コマンドを使い、*.cnb.md ファイルを効率的に編集するための手順です。

前提 ​

  • Cursor v2.4 以降（Skills 対応バージョン）
  • cdm コマンドがインストール済み（はじめにを参照）
  • cdm auth login で PAT が登録済み

セットアップ方針 ​

エージェントに *.cnb.md の編集ルールを伝える方法として、Cursor では Rules と Skills の2つが利用できます。

  • Rules: ファイル種別（globs）で適用範囲を制御できる。*.cnb.md を開いた時だけ確実に適用したい場合に向く
  • Skills: エージェントが「読む・編集する」と判断したタイミングで起動する。複数の Skill を組み合わせて使いやすい

どちらか一方でも動作しますが、Skill の配置を推奨します。Skill は判断ベースで起動するため、エージェントが *.cnb.md を読むだけの場面でも適切にガイドを参照できます。両方設定しても問題ありません。

Skill の配置 ​

*.cnb.md ファイルの編集時に起動し、cdm CLI と PAT の確認、エージェント向けガイドの取得を行う Skill を配置します。

プロジェクトルートに .cursor/skills/cdm/SKILL.md を作成し、以下の内容を保存してください。

md
---
name: cdm
description: Use this skill when reading or editing any *.cnb.md notebook file. Loads the cdm agent workflow guide and verifies the cdm CLI / PAT are available before making changes.
---

# Editing cdm notebook files

This skill applies whenever you are about to read or edit a `*.cnb.md` notebook file.

## Steps

1. Verify that the `cdm` command is available and the PAT is valid:

```sh
   cdm --version
   cdm auth whoami
```

   - If `cdm --version` fails with "command not found", stop and ask the user to install `cdm`. Do not attempt to install it yourself. Point them to the "Getting Started" page in the cdm docs.
   - If `cdm auth whoami` returns `Status: INVALID` or exits with code 1, stop and ask the user to re-register the PAT via `cdm auth login`.

2. Fetch the agent workflow guide via the cdm CLI:

```sh
   cdm doc show /guide/for-agents.md
```

3. Follow the workflow defined in that guide. The guide will direct you to fetch additional documentation pages as needed for the specific edit you are making (chart settings, grid layouts, SQL blocks, parameters, etc.).

4. After editing, run `cdm notebook format` to verify and auto-repair the file.

ファイル作成後、Cursor のウィンドウを再読み込み（Cmd/Ctrl+Shift+P → Developer: Reload Window）してください。

Rules の配置（代替手段） ​

Skill の代わりに、または併用する形で Rules を設定することもできます。.cursor/rules/cdm.mdc を作成してください。

md
---
description: cdm notebook files (*.cnb.md) editing rules
globs:
  - "**/*.cnb.md"
alwaysApply: false
---

When editing `*.cnb.md` files in this project, you must:

1. Verify that `cdm --version` and `cdm auth whoami` both succeed in the shell.
   - If `cdm` is not installed, stop and ask the user to install it (see the "Getting Started" page).
   - If the PAT is invalid, stop and ask the user to re-register via `cdm auth login`.
2. Fetch the agent workflow guide via the cdm CLI: run `cdm doc show /guide/for-agents.md`.
3. Follow the workflow defined in that guide.

globs で *.cnb.md ファイルを開いたときのみルールが適用されるようにしているため、それ以外のファイル編集時には影響しません。

トラブルシューティング ​

Skill / Rules が認識されない ​

  • .cursor/skills/cdm/SKILL.md または .cursor/rules/cdm.mdc のパス構造になっているか確認してください
  • Cursor のウィンドウ再読み込み（Developer: Reload Window）を実行してください

cdm コマンドが見つからない ​

エージェントが「cdm: command not found」と報告した場合、グローバルインストールが必要です。詳細ははじめにを参照してください。

API コマンドが失敗する ​

  • cdm auth whoami で PAT が有効か確認してください
  • ノートブックファイルのフロントマター workspace_id と、利用中の profile のワークスペースが一致しているか確認してください