mcpField
B
buildin-cli

buildin-cli

github.com/next-space生産性0217 回インストール2 週間前に更新
リポジトリ

buildin-cli について

Buildin CLI は、Buildin V2 API を操作するためのコマンドラインスキルです。ページ、ブロック、データベース、検索、Markdown、ファイルを扱い、API 操作前の CLI と認証状態の確認、ヘルプやエンドポイント文書の参照を定めています。

主な機能

  1. 01ページ、ブロック、データベースの操作
  2. 02テキスト検索とセマンティック検索
  3. 03ページの Markdown の取得と置換
  4. 04ファイルのアップロードとファイルブロックの追加
  5. 05書き込み前の対象と影響の確認

活用シーン

  1. 01コマンドラインから Buildin のページを取得・更新
  2. 02データベースを検索してレコード属性を確認
  3. 03ワークスペースを検索またはファイルをアップロード

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/next-space/buildin-skill --skill buildin-cli

インストール後、Claude Code で/buildin-cliを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

agents/
openai.yaml
references/
block-own-text.md
native-database-fields.md

詳細

Buildin CLI

Buildin V2 API での作業（ページ、ブロック、データベース、検索、Markdown コンテンツ、ファイル）には、Buildin CLI（buildin）を使用します。

ユーザーが許可した操作は、インストール済みの CLI を通じて実行してください。実行を依頼された場合、コマンドの説明だけで終わらせないでください。ネイティブのデータベースフィールドを扱う場合は、リクエストファイルを準備する前に操作手順を読んでください。スキーマ、レコードのリレーション、数式の読み取り、検証について説明しています。

CLI のソースリポジトリは非公開の場合があります。CLI を使う前に、ユーザーにソースコードのクローンを依頼しないでください。リリース済みバイナリを公式 Buildin CDN からインストールまたは更新するのは、ユーザーが明示的に承認した後に限ります。

Buildin の作業には、Buildin コマンド、Buildin ベース URL、BUILDIN_* 環境変数、および Buildin 認証情報ストアのみを使用してください。

必須の事前確認

リモートの Buildin API を呼び出す前に、この事前確認を完了してください。CLI のヘルプ、エンドポイントのドキュメント、オフラインでの計画には、認証は必要ありません。

  1. CLI が利用可能かどうかを、インストールや更新をせずに確認します。
if command -v buildin >/dev/null 2>&1; then
  buildin version
else
  echo "Buildin CLI is not installed"
fi

CLI がない場合、または古い場合は、公式インストーラーが https://cdn.buildin.ai/buildin-cli/install（Windows の場合は https://cdn.buildin.ai/buildin-cli/install.ps1）で入手できることを説明してください。ユーザーが明示的に承認するまで、ダウンロード、実行、更新を行わないでください。

承認を得た後は、公式 URL とユーザーが承認したバージョンのみを使用してください。インストーラーを一時ファイルにダウンロードし、その出所、バージョン、SHA-256 ハッシュを提示してください。実行前に、公式のチェックサムまたは署名と照合します。公式の整合性確認データがない場合は中止し、未検証のインストーラーを実行するのではなく、手動インストールを提案してください。試行後は、一時インストーラーファイルを削除してください。

  1. CLI がインストールされている場合は、認証状態とアクティブな ID を確認します。
buildin --json doctor
buildin --json whoami

確認の結果、Buildin の認証情報で認証済みである場合にのみ続行してください。認証情報がない、または無効な場合は、自動的にログインフローを開始しないでください。利用可能な方法を説明し、ユーザーが明示的に選択するまで待ってください。

  • BUILDIN_TOKEN がすでに設定されている場合は、buildin --json doctor と buildin --json whoami を再実行してください。別のログイン方法を尋ねないでください。
  • ブラウザーログイン：buildin login --browser。
  • ヘッドレス環境での手動セットアップ：buildin --json login --manual。
  • 承認済みのシークレットチャネルを通じて、BUILDIN_TOKEN または保存済みの認証情報を設定します。

エージェントセッションでは、対話形式の方法選択プロンプトで停止する可能性があるため、プレーンな buildin login を実行しないでください。認証を確認するまで、API 呼び出しや不完全なデータに基づく結論の提示を行わないでください。ユーザーがログイン方法を明示的に承認した後は、選択された方法のみを実行し、その後 buildin --json doctor と buildin --json whoami を再実行してください。

ユーザーがブラウザーログインを明示的に選択した後に限り、次のブラウザーログインコマンドを使用してください。

buildin login --browser

ユーザーがヘッドレス環境またはリモート環境での手動セットアップを明示的に選択した後に限り、手動セットアップを行ってください。

buildin --json login --manual

コマンドが見つからない場合や、ヘルプ出力が古いように見える場合は、buildin update で CLI を更新できることを説明し、実行前にユーザーの明示的な承認を待ってください。

便利なインストール用オーバーライド：

  • BUILDIN_INSTALL_DIR - インストール先ディレクトリ。
  • BUILDIN_VERSION - v0.1.10 のような正確なリリースバージョン。
  • BUILDIN_CLI_RELEASE_BASE_URL - テスト用の代替リリースベース URL。

最初のルール：CLI に尋ねる

CLI は自己文書化されています。構文やリクエストフィールドを推測するより、次のコマンドを優先してください。

  • buildin --help - グローバルオプションとトップレベルコマンドを一覧表示します。
  • buildin help <command...> - 任意のコマンドまたはサブコマンドの使用方法、オプション、例、注意事項を表示します。
  • buildin api ls - 公開 API エンドポイントとリクエストフィールドのヒントを一覧表示します。
  • buildin api ls --plain - 確認しやすい簡潔なエンドポイント一覧を表示します。
  • buildin api --docs <PATH> -X <METHOD> - 1 つのエンドポイントについて、パラメーター、例、安全上の注意事項を含む、エージェントが読み取れる Markdown ドキュメントを表示します。
  • buildin api --spec <PATH> -X <METHOD> - 1 つのエンドポイントの埋め込み OpenAPI フラグメントをそのまま表示します。
  • buildin --json doctor - 認証またはベース URL の選択が不明確な場合に、ローカルの認証と構成の状態を調べます。
  • buildin --json whoami - アクティブな Buildin の ID を確認します。
  • buildin markdown get <page-id> - ページの内容を Markdown として取得します。

構文、リクエストボディのフィールド、ページネーション、認証情報の取得元、またはコマンドの対応範囲が不明な場合は、まずヘルプを実行してください。

認証情報と構成

CLI は次の優先順位で認証情報を解決します。

  1. --token <token>
  2. BUILDIN_TOKEN
  3. Buildin の認証情報ストアに保存されたログイン認証情報

これは CLI の解決動作であり、認証情報を公開してよいという意味ではありません。エージェントのコマンド、ログ、共有シェルでは --token を渡さないでください。プロセス一覧やシェルの履歴から漏れる可能性があります。ユーザーにベアラートークンをチャットに貼り付けるよう求めないでください。事前設定された BUILDIN_TOKEN、保存済みの認証情報、または承認されたシークレット経路を使用し、コマンド出力に認証情報が含まれている場合は必ずマスキングしてください。

認証情報が設定されていない場合は、ブラウザーログイン、手動設定、または承認されたシークレット経路を提示し、ユーザーの選択を待ってください。選択されたログインが成功したら、buildin --json doctor と buildin --json whoami を再実行してください。

OAuth の更新とサンドボックスの権限

保存されたブラウザー OAuth 認証情報では、読み取り専用の API コマンドでも認証情報ストアへの書き込みアクセスが必要になる場合があります。これは、CLI が API リクエストを送信する前にトークンをローテーションし、アトミックに保存するためです。

  • error.code が credential_store_permission_denied、または needsCredentialWritePermission が true の場合は、ログインを開始しないでください。credentialsPath を含むディレクトリへの、範囲を限定した書き込みアクセスを要求してから、buildin --json doctor と元のコマンドを再実行してください。再認証ではローカルファイルシステムの拒否を解決できません。
  • エラーコードが oauth_refresh_failed または oauth_refresh_rejected で、reauthorizationRequired が false の場合は、同じコマンドを後で再試行してください。ログインを開始しないでください。
  • ログインを提示するのは、reauthorizationRequired または refreshTokenExpired が true の場合、あるいは OAuth が更新トークンは無効、期限切れ、または取り消し済みであると明示的に報告した場合に限ります。
  • 古い CLI バージョンでは、Operation not permitted または OS エラー 1 のみが報告される場合があります。更新可能な OAuth 認証情報が保存されている場合は、トークンが取り消されたと判断する前に、これを認証情報ストアのサンドボックスによる拒否の可能性が高いものとして扱い、報告されたパスとサンドボックスを確認してください。

credentials.json をワークスペースにコピーしたり、その内容を公開したりしないでください。

一般的な環境変数：

  • BUILDIN_TOKEN - API 呼び出し用のベアラートークンです。
  • BUILDIN_BASE_URL - API のベース URL。デフォルトは https://api.buildin.ai です。
  • BUILDIN_CONFIG_DIR - 構成ディレクトリ。デフォルトは Buildin プロファイルに従います。
  • BUILDIN_USER_AGENT - カスタムユーザーエージェントのサフィックスです。

ベアラートークンを表示したり、ファイルに書き込んだり、リクエストボディに貼り付けたりしないでください。Buildin V2 API を curl で呼び出さないでください。認証、製品のデフォルト設定、リトライ、エラー形式を一貫させるため、CLI を使用してください。

作業ルール

  • 安定した機械可読形式の標準出力には --json を使用します。ok:true を必須とし、data 内の API オブジェクトを読み取ります（作成された ID は data.id です）。ok:false の場合は error を確認し、コマンドの失敗を処理の完了と見なさないでください。
  • JSON リクエスト本文はローカルファイルに保存し、--body <file> で渡します。
  • Markdown の置換内容はローカルファイルに保存し、--file <file> で渡します。
  • api call よりもドメインコマンドを優先します。推奨されるドメインコマンドがある場合は、buildin api --docs に記載されています。
  • ページネーションに対応したコマンドでは、JSON 出力でカーソルを確認し、コマンドのカーソルオプションを指定して繰り返し実行します。

書き込みの安全性

リモートでの作成、更新、追記、アップロード、置換、または API への直接書き込みを行う前に、次の点を確認してください。

  1. 対象、操作、想定される影響（レコード数、影響を受けるブロック、アップロードするファイルなど）を正確に確認します。
  2. 可能であれば、まず現在の対象を読み取ります。Markdown を置換する場合、ユーザーが全体置換を明示的に許可していない限り、既存の内容と比較してください。CLI でバージョンや ETag を利用できる場合は、--if-match を使用します。
  3. ユーザーの依頼は、依頼された変更を許可するものです。読み取り結果または作成結果から ID を特定し、その範囲内で通常の実装上の詳細を選択します。生成された ID の提示や既存の承認の再確認をユーザーに求める必要はありません。対象が曖昧なままの場合、または変更が依頼の範囲を超える場合に限り、確認してください。
  4. ファイルと外部 URL がユーザーの許可を得たものであり、対象のワークスペースに含める意図のない認証情報や個人データが含まれていないことを確認します。

CLI は意図的に DELETE API 呼び出しを拒否します。このスキルでは、回避策を実行したり提案したりしません。削除には、二度目の確認を伴う専用のワークフローを使用してください。

一般的なワークフロー

ページを読む
buildin --json page get <page_id>
buildin markdown get <page_id> > page.md

ページの内容を扱う場合は、可能な限り Markdown を使用してください。生のブロック JSON よりも確認、編集、差分の比較が容易です。

ページの Markdown を置換する
buildin markdown put --file page.md <page_id>

対象ページの ID と置換ファイルを確認してから実行してください。

JSON でページを作成または更新する

ローカルに JSON 本文ファイルを作成し、CLI に渡します。

buildin --json page create --body page.json
buildin --json page update --body patch.json <page_id>

冪等性のある作成には、--idempotency-key <key> を使用します。

ブロックと子要素

コールアウト／トグルの先頭行の編集、空のプレースホルダー、または子段落からのタイトルの移動については、独自のテキストと子要素を参照してください。 callout.rich_text はコールアウトで最初に編集可能な行、toggle.rich_text は折りたたみタイトルです。children は独立したブロックです。ブロック自体とその子要素の両方を読み取ってください。Markdown だけでは同等のレイアウトであることを確認できません。

buildin --json block get <block_id>
buildin --json block children <block_id>
buildin --json block append <block_id> --body children.json
buildin --json block update <block_id> --body block-patch.json
データベース
buildin --json database get <database_id>
buildin --json database query <database_id> --body query.json
buildin --json database create --body database.json
buildin --json database update <database_id> --body patch.json
buildin --json page property get <page_id> <property_id>

query.json を作成する前に、buildin api --docs またはコマンドのヘルプで、フィルターとソートの本文形式を確認してください。

検索
buildin --json search text "roadmap" --page-size 10
buildin --json search semantic "tasks about quarterly planning" --space-id <space_id> --page-size 10

正確なタイトル、キーワード、既知のフレーズを検索するにはテキスト検索を使用します。正確な表現よりも意図が重要な場合は、セマンティック検索を使用します。

ファイル

親ページにローカルファイルをアップロードします。

buildin --json file upload --parent-page <page_id> ./report.pdf

返されたオブジェクト名とサイズを指定して、Buildin がホストするファイルブロックを追記します。

buildin --json block append-file <block_id> --oss-name <oss_name> --size <bytes>

外部ファイルの URL を追記します。

buildin --json block append-file <block_id> --external-url https://example.com/report.pdf

API 呼び出しへのフォールバック

エンドポイントに対応するドメインコマンドがない場合に限り、api call を使用します。検索手順は次のとおりです。

buildin api ls --plain
buildin api --docs /v2/blocks/{block_id}/children -X PATCH
buildin api --spec /v2/blocks/{block_id}/children -X PATCH
buildin --json api call PATCH /v2/blocks/:block_id/children --param block_id=<block_id> --body body.json

POST、PUT、または PATCH の場合は、先に --docs と --spec を読み、上記の書き込みの安全性に関するルールを適用してください。--param はパスのプレースホルダーに優先して値を設定します。残りのキーはクエリパラメーターになります。If-Match などのシークレットではないヘッダーに限り、--header NAME=VALUE を使用してください。認証情報やセッション情報をヘッダーに含めないでください。

トラブルシューティング

  • コマンドが見つからない場合：公式インストーラー https://cdn.buildin.ai/buildin-cli/install を提示し、使用する前に明示的な承認を待ちます。
  • 不明なコマンドまたはオプションの場合：buildin update を実行する前に承認を求め、その後 buildin <command> --help を実行します。
  • 認証に失敗した場合：buildin --json doctor を実行し、上記の OAuth リフレッシュおよびサンドボックス権限のルールに従います。すべての失敗や HTTP 401 を、リフレッシュトークンの期限切れと同一視しないでください。
  • API の形式が想定外の場合：再試行する前に buildin api --docs <PATH> -X <METHOD> と buildin api --spec <PATH> -X <METHOD> を実行します。

コメント

Markdown 対応