heptabase-cli

前提条件

• デスクトップアプリから CLI をインストールします。コマンドは macOS/Linux では heptabase です。Windows では、cmd/PowerShell 用の heptabase.cmd と、POSIX シェル用の heptabase シムがインストールされます。
• 使用前に heptabase --version でバージョンの互換性を確認してください。インストールされている CLI のバージョンがこのスキルの互換性範囲（0.8.x）外の場合は、続行せず、Heptabase デスクトップアプリまたはこのスキルパッケージのいずれかを更新するようユーザーに依頼する必要があります。

コマンドの確認

heptabase help を実行すると、利用可能なすべてのトップレベルコマンドを確認できます。これは常に最新の情報です。各コマンドでは、詳細な使い方を確認するために --help を使用できます。

heptabase help
heptabase note --help
heptabase note create --help

よく使うレシピ

よくあるリクエストには、次のクイックレシピをお使いください。あまり使わないフラグを確認する場合やコマンドが失敗した場合は、heptabase help または <command> --help を実行して正しい構文を確認してください。

• 最近のカード： heptabase card list --sort createdTime --direction descending --limit 20
• 今日の日記： heptabase journal read $(date +%Y-%m-%d)
• キーワードでカードを検索： heptabase card list -q "<keyword>" --limit 20
• Markdown からノートを作成： heptabase note create --content "# Title\n\nBody"（デフォルトで「AI による作成」として記録されます。人が作成したコンテンツとして扱うには、--no-created-by-ai を追加してください。）
• Markdown から今日の日記を作成： heptabase journal create --content "Body"（デフォルトで「AI による作成」として記録されます。人が作成したコンテンツとして扱うには、--no-created-by-ai を追加してください。）
• ノートに Markdown を追記： heptabase note append <cardId> --content "More content"。
• JSON を保存してノートの内容を編集： まず references/card-content-schema.md を読み、次に heptabase note read <cardId> を実行します。返された ProseMirror JSON を編集し、heptabase note save <cardId> --content-md5 <contentMd5> --content-file <path> で保存してください。
• プロパティを操作： heptabase tag cards <tagId> --include-properties を使って、値を含むタグ付きカードを一覧表示するか、heptabase card properties <cardIdOrDate> を使ってカードを確認してください。書き込む前に references/property-values.md を読み、heptabase tag properties <tagId> で定義を確認してから、文字列や選択肢には heptabase card set-property <cardIdOrDate> --property-id <propertyId> --value "Published"、型付き JSON 値には --json-value ... を使用してください。
• 解析済み PDF の内容を読む： まず references/pdf-reading.md を読み、次に heptabase pdf metadata <pdfCardId> を使って totalPages を確認します。heptabase pdf read <pdfCardId> --start-page N --end-page N でページ範囲を読み取ってください。
• 文字起こしの内容を読む： まず references/transcript-reading.md を読み、次に heptabase audio metadata <audioCardId> または heptabase video metadata <videoCardId> を使って transcriptStatus と durationSeconds を確認します。heptabase audio read <audioCardId> --start-seconds 0 --end-seconds 300 または heptabase video read <videoCardId> --start-seconds 0 --end-seconds 300 で、時間範囲内の重複する文字起こしエントリを読み取ってください。
• 添付ファイルを読む： まず references/file-reading.md を読みます。必要に応じて heptabase file list --card-id <cardId> で ID を確認し、mktemp -d を実行してから heptabase file export <fileId> --output-dir <scratchDir> を実行してください。返された path を、使用環境に標準搭載されているファイル読み取りツールで読み取ってください。
• ローカル画像をノートに追加： まず references/image-import.md を読み、次に heptabase file import <path> を実行します。note read と note save を使って image ノードを追加し、fileId を設定して、originalWidth と originalHeight には返された width と height を設定してください。
• ホワイトボードを確認： heptabase whiteboard read <whiteboardId> --mode structure を実行し、続けて heptabase whiteboard read-layout <whiteboardId> を実行してください。
• チャットメッセージを読む： whiteboard read の出力からチャット ID をコピーし、heptabase object read chat <chatId> --offset <n> --limit <n> を使って、削除されていないメッセージをページ分割して読み取ります。各メッセージには、表示されている投稿者、タイムスタンプ、引用された内容、メッセージ本文が含まれます。ホワイトボードのチャットメッセージ要素には、heptabase object read chatMessagesElement <elementId> --offset <n> --limit <n> を使ってください。
• ホワイトボードのレイアウトを確認または表示： heptabase whiteboard lint <whiteboardId> を実行してください。視覚的に確認するには、まず references/whiteboard.md を読み、次に heptabase whiteboard screenshot <whiteboardId> --output <existingDirectory>/whiteboard.png を使って、返されたローカルパスを確認してください。
• ホワイトボードのレイアウトまたはマインドマップを変更： まず references/whiteboard.md を読みます。マインドマップの場合は、references/mind-maps.md も読んでください。ネストされた入力またはバッチ入力を使うコマンドでは、--input <path|-> と標準形式の JSON を使用します。

Heptabase URL（ディープリンク）

ユーザーが Heptabase URL（ディープリンクとも呼ばれます）を共有した場合は、CLI を使用して読み取ってください。ユーザーから明示的に求められていない限り、ブラウザーで開かないでください（アプリでは認証が必要で、エージェントが使用するブラウザーには通常ログインしていません）。

URL のパターンと処理方法：

• ジャーナルカード： https://app.heptabase.com/<workspaceId>/card/<YYYY-MM-DD> → heptabase journal read <YYYY-MM-DD>
• UUID で指定するカード： https://app.heptabase.com/<workspaceId>/card/<uuid> → まず heptabase card properties <uuid> を実行してカードの種類を確認し、対応するコマンド（heptabase note read <uuid>、heptabase pdf metadata <uuid> など）で内容を読み取ります。
• ホワイトボード： https://app.heptabase.com/<workspaceId>/whiteboard/<uuid> → heptabase whiteboard read <uuid> --mode structure と heptabase whiteboard read-layout <uuid> を実行します。レイアウトの変更や視覚的な判断を行う前に、references/whiteboard.md を読んでください。

URL 内の <workspaceId> は CLI では不要です。カードまたはホワイトボードの ID のみを抽出してください。

ノートとジャーナルカードの内容編集

通常の文章作成には、Markdown を使って create／append を使用してください。ProseMirror JSON を使って heptabase note save／heptabase journal save を実行する前に、必ず references/card-content-schema.md を読んでください。また、カードへのメンション、ホワイトボードへのメンション、日付、動画、数式、トグル／ToDo リストなど、Heptabase 固有の拡張機能を使った Markdown を生成する前にも読んでください。

AI 作成済みのマーク

note create と journal create は、デフォルトでコンテンツに「AI 作成済み」のマークを付けます。--no-created-by-ai を付けるかどうかを判断する前に、必ず references/created-by-ai.md を読んでください。

プロパティの編集

プロパティ値を設定する前に、必ず references/property-values.md を読み、heptabase card properties <cardIdOrDate> および／または heptabase tag properties <tagId> で対象のプロパティを確認してください。プロパティの形式は種類によって異なり、リレーションへの書き込みではリレーション値全体が置き換えられます。リレーションプロパティの場合は、heptabase tag properties <sourceTagId> を使ってプロパティ定義の relationTargetTagId を取得し、書き込む前に有効な関連カードを一覧表示してください。

ファイルの読み取り

ファイルの読み取り、一覧表示、またはエクスポートを行う前に、必ず references/file-reading.md を読んでください。

画像のインポート

画像をインポートする前、またはノートに追加する前に、必ず references/image-import.md を読んでください。

PDF の読み取り

解析済みの PDF コンテンツを読む前に、必ず references/pdf-reading.md を読んでください。

トランスクリプトの読み取り

解析済みのメディアのトランスクリプトを読む前に、必ず references/transcript-reading.md を読んでください。

ホワイトボードでの作業

意図的な配置、移動、整列、サイズ変更、セクション分け、接続、削除、または視覚的な検証を行う前に、必ず references/whiteboard.md を読んでください。正確な配置基準、選択対象と移動先の形状、読み取り前提の書き込みルール、検証ループが定義されています。

マインドマップの作成や構造の編集を行う場合は、references/mind-maps.md も読んでください。更新する前に現在のマインドマップを再度読み込み、構造ノードの安定した ID が最新であることを確認してください。

既存の whiteboard cards、add-card、remove-card コマンドは、限定的な旧式コマンドです。構造化されたホワイトボード作業では、whiteboard read、read-layout、および標準の --input コマンドを優先してください。

標準の変更コマンドは、ホワイトボードの階層とショートカット、オブジェクトの配置と別のホワイトボードへの移動、移動、整列、配置調整、サイズ変更、色の変更と削除、セクションと接続、マインドマップの作成と更新に対応しています。現在の一覧を確認するには heptabase whiteboard --help を実行し、ネストされた入力についてはリンク先のリファレンスを読んでください。

標準的な JSON 入力

ネストされたデータや一括データを扱うコマンドでは、--input <path|-> を指定できます。- を指定すると、標準入力から JSON を読み取ります。jq で JSON を作成するか、一時ファイルに書き込んでください。信頼できないテキストを、手作業で組み立てたシェルの JSON に埋め込まないでください。

すべての変更結果を確認してください。処理されたトップレベルの status: "failed" は出力され、終了ステータス 1 で終了します。トップレベルの処理が成功すると、項目の結果に failureReasonCode フィールドが含まれていても終了ステータス 0 で終了するため、全面的な成功を報告する前に、それらを確認してください。

すべての出力は JSON

すべてのコマンドは JSON を標準出力に出力します。jq で解析したり、他のツールにパイプしたりできます。whiteboard screenshot は PNG を --output に書き込み、メタデータのみを出力します。画像のバイト列は出力しません。

トラブルシューティング

• デスクトップアプリが起動している必要があります。 CLI はアプリ内のローカルサーバーと通信します。アプリが閉じていると、すべてのコマンドが失敗します。heptabase start を実行して起動し、準備が整うまで待ってください。
• Codex のサンドボックスによって、ローカル CLI サーバーがブロックされる場合があります。 Heptabase が起動しているのに Codex が CLI サーバーの準備ができていないと表示する場合は、references/codex-sandbox.md を参照してください。Codex が権限昇格に対応している場合は、サンドボックスの外で heptabase コマンドを再試行してください。
• 変更操作は直列化されます。 競合を防ぐため、書き込み操作は一度に 1 つずつ実行されます。読み取りは並行して実行されます。
• リクエストボディのサイズ制限。 サーバーは、1 MB を超える JSON リクエストボディを拒否します。file import では、最大 2000 MB のファイルをアップロードできます。
• リクエストのタイムアウト。 サーバーは、ボディの送信に 10 秒を超える JSON リクエストをタイムアウトします。

既知の制限事項

• ローカルサーバーの自動有効化／CLI の自動インストールには対応していません。 ローカル CLI サーバーが無効になっている場合や、CLI の設定がない場合、スキル単独では修復できません。まずデスクトップアプリの設定で Local CLI Server と CLI install を有効にするよう、ユーザーに依頼してください。
• ファイルのエクスポートはローカルファイルのみ対応しています。 heptabase file export は、ファイルのメタデータと実ファイルがデスクトップアプリでローカルに利用可能な場合にのみ動作します。クラウドストレージから不足しているファイルをダウンロードすることはありません。
• インポートできるのは画像のみです。 heptabase file import では、ノートで使う画像をインポートできます（HEIC、HEIF、TIFF は対象外です）。PDF、音声、動画、その他のファイルはインポートできず、カードの作成やメディア処理 API の呼び出しにも対応していません。
• ホワイトボードで扱える範囲には意図的に制限があります。 CLI では、ホワイトボードやその基になる Card の削除、スペース間でのコンテンツの移動、任意の図形の作成、意味に基づいてボード全体を自動レイアウトする単一コマンドの実行はできません。remove-objects が削除するのはキャンバス上の配置であり、元の Card ではありません。
• CLI に元に戻すコマンドや Agent 履歴はありません。 ホワイトボードの変更操作ではアプリの通常のドメインアクションを使用しますが、CLI では Agent チャットの取り消し、ツール呼び出しの永続化、Agent のスクリーンショットチェックリストは利用できません。まず読み取りを行い、自分で結果を確認してください。
• ホワイトボードのコンテンツはローカルにあります。 ホワイトボードの読み取りでは、実行中のデスクトップアプリで利用可能なコンテンツを使い、バックエンドのみで行われる PDF、ウェブ、YouTube の情報補完は実行しません。ソースの完全なコンテンツを取得するには、専用の PDF コマンドやメディアコマンドを使用してください。ウェブカードの完全なコンテンツは CLI から利用できません。ホワイトボードの出力に含まれるソース URL を使用してください。
• スクリーンショットは概略図です。 空間的な確認には使えますが、意味に基づく読み取りや決定的なリントの代わりにはなりません。
• プロパティによる絞り込みには、まだ対応していません。 タグのプロパティスキーマの読み取り、プロパティ値の読み取り、カードのプロパティ値 1 つの設定はできますが、プロパティ値によるカードの検索はできません。

警告

• データへのアクセスには CLI のみを使用してください。 ローカルのデータベースファイル、アプリのストレージ、キャッシュファイル、内部エンドポイント、その他 CLI 以外の方法を通じて、Heptabase のアプリデータを直接読み取ったり、書き込んだり、変更したりしないでください。CLI が要求された操作に対応していない場合は、そこで止めて、未対応であることを報告してください。