flowus-cli

FlowUs CLI

FlowUs V2 API を操作するには、FlowUs CLI（flowus）を使用します。ページ、ブロック、データベース、検索、Markdown コンテンツ、ファイルを扱えます。

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

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

必須の事前確認

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

1. インストールや更新をせずに、CLI が利用可能かどうかを確認します。

if command -v flowus >/dev/null 2>&1; then
  flowus version
else
  echo "FlowUs CLI is not installed"
fi

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

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

2. CLI がインストール済みの場合は、認証と有効なユーザー ID を確認します。

flowus --json doctor
flowus --json whoami

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

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

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

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

flowus login --browser

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

flowus --json login --manual

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

インストール時に使用できるオーバーライド：

• FLOWUS_INSTALL_DIR - インストールディレクトリ。
• FLOWUS_VERSION - v0.1.10 などの正確なリリースバージョン。
• FLOWUS_CLI_RELEASE_BASE_URL - テスト用の代替リリースベース URL。

まずは CLI に確認する

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

• flowus --help - グローバルオプションと最上位コマンドを一覧表示します。
• flowus help <command...> - 任意のコマンドまたはサブコマンドについて、使い方、オプション、例、注意事項を表示します。
• flowus api ls - 公開 API エンドポイントとリクエストフィールドのヒントを一覧表示します。
• flowus api ls --plain - 確認しやすい簡潔なエンドポイント一覧を表示します。
• flowus api --docs <PATH> -X <METHOD> - 1 つのエンドポイントについて、パラメーター、例、安全上の注意を含む、エージェントが読み取れる Markdown ドキュメントを表示します。
• flowus api --spec <PATH> -X <METHOD> - 1 つのエンドポイントに対応する、埋め込み済みの OpenAPI フラグメントをそのまま表示します。
• flowus --json doctor - 認証またはベース URL の選択が不明な場合に、ローカルの認証状態と設定状態を調べます。
• flowus --json whoami - 有効な FlowUs のユーザー ID を確認します。
• flowus --json workspace - 現在のワークスペースと認証情報の境界を調べます。
• flowus --json workspace directory - お気に入り、チーム、共有、プライベートのサイドバーセクションを一覧表示します。
• flowus --json fetch <link-or-id> - FlowUs のリンクまたは ID を解決し、該当するページ、データベース、またはブロックを読み取ります。
• flowus markdown get <page-id> - ページの内容を Markdown として取得します。

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

認証情報と設定

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

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

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

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

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

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

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

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

一般的な環境変数：

• FLOWUS_TOKEN - API 呼び出し用のベアラートークン。
• FLOWUS_BASE_URL - API のベース URL。デフォルトは https://api.flowus.cn です。
• FLOWUS_CONFIG_DIR - 設定ディレクトリ。デフォルトは FlowUs プロファイルに従います。
• FLOWUS_USER_AGENT - カスタムユーザーエージェントのサフィックス。

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

作業ルール

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

書き込みの安全性

リモートでの作成、更新、追記、アップロード、置換、または生の API 書き込みを行う前に、次のことを確認します。

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

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

一般的なワークフロー

ページ、メンバー、オブジェクトを確認する

flowus --json workspace
flowus --json workspace directory --page-size 100
flowus --json page list --page-size 100
flowus --json page list --parent-id <page_id> --page-size 100
flowus --json page team --page-size 100
flowus --json page private --page-size 100
flowus --json page shared --page-size 100
flowus --json page favorites --page-size 100
flowus --json user ls --query "display name" --page-size 100
flowus --json fetch <link_or_id>

page list は、ページに類する子要素を 1 階層分返します。--parent-id を省略すると、ワークスペースのルートが一覧表示されます。返されたノードに子要素がある場合は、その ID を --parent-id に渡して次の階層を確認します。特定の親ではなく FlowUs のサイドバーを参照するタスクでは、セクションコマンドを使用します。user ls --query はメールアドレスではなく、表示名を検索します。

ページを読み取る

flowus --json page get <page_id>
flowus markdown get <page_id> > page.md

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

ページの Markdown を置換する

flowus markdown put --file page.md <page_id>

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

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

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

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

冪等な作成には --idempotency-key <key> を使用します。

ページを編集または複製する

flowus --json page edit <page_id> --old "old text" --new "new text"
flowus --json page duplicate <page_id> --parent-id <parent_id> --title "Copy title"

page edit は、デフォルトで完全一致する一意の対象を要求します。すべての出現箇所を置き換える意図がある場合に限り、--replace-all を使用します。複製する前に、元のページを読み取り、移動先の親を確認してください。--parent-id を省略すると、コピーは元のページと同じ場所に作成されます。

ブロックと子要素

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

flowus --json block get <block_id>
flowus --json block children <block_id>
flowus --json block append <block_id> --body children.json
flowus --json block update <block_id> --body block-patch.json

データベース

flowus --json database get <database_id>
flowus --json database query <database_id> --body query.json
flowus --json database mutate <database_id> --body mutation.json --idempotency-key <key>
flowus --json database view list <database_id>
flowus --json database view get <database_id> <view_id>
flowus --json database view create <database_id> --body view.json --idempotency-key <key>
flowus --json database view update <database_id> <view_id> --body view-patch.json --if-match <etag>
flowus --json page property get <page_id> <property_id>

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

アトミックで権限チェック済みのデータベース書き込みには、database mutate を使用します。データベースを先に読み取り、変更には安定したプロパティ ID を使用し、安定した冪等性キーを使用してください。レコードの作成を依頼された場合、既存のレコードを上書きしないでください。正確な本文形式は flowus api --docs で確認してください。

データベースビューの作成には、安定した冪等性キーを使用します。更新前にビューを読み取り、返された弱い ETag を --if-match とともに渡すことで、同時変更を検出し、黙って上書きされるのを防ぎます。

検索

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

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

ファイル

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

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

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

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

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

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

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

エンドポイントを対象とするドメインコマンドがない場合に限り、api call を使用します。次の順序で確認します。

flowus api ls --plain
flowus api --docs /v2/blocks/{block_id}/children -X PATCH
flowus api --spec /v2/blocks/{block_id}/children -X PATCH
flowus --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://cdn2.flowus.cn/flowus-cli/install を案内し、使用する前に明示的な承認を待ちます。
• 不明なコマンドまたはオプションの場合：flowus update を実行する前に承認を求め、その後 flowus <command> --help を実行します。
• 認証に失敗した場合：flowus --json doctor を実行し、上記の OAuth 更新およびサンドボックス権限に関するルールに従います。すべての失敗や HTTP 401 を、リフレッシュトークンの期限切れとみなさないでください。
• 予期しない API の形式の場合：再試行する前に、flowus api --docs <PATH> -X <METHOD> と flowus api --spec <PATH> -X <METHOD> を実行します。