basecamp

Basecamp CLI

コマンドのリファレンスとして、インストール済みの CLI を使用してください。このスキルでは運用ルールを定義しており、意図的に CLI のコマンド一覧を重複して記載していません。

発見を優先するワークフロー

各タスクでは、次の手順に従ってください。

1. ユーザーの言葉から、最も深い階層にあると思われる末端コマンドを推測します。

2. この会話内のツールの結果ですでに正確な引数やフラグが確認できていない場合は、その末端コマンドを直接確認します。

   basecamp <group> <subcommand> --agent --help
   

3. 末端コマンドが存在しない場合は、最も近い親グループを確認します。トップレベルグループ自体が不明な場合に限り、ルートヘルプを使用します。

   basecamp <group> --agent --help   # fallback
   basecamp --agent --help           # last resort
   

4. 末端コマンドの usage、args、flags、notes を信頼できる情報源として扱います。位置引数、フラグ、エイリアス、スコープ、またはグループを引数なしで実行できるかどうかを推測してはいけません。

5. 明示的に出力モードを指定して実行し、次の対応を判断する前に、構造化されたエラーと補足情報を確認します。

対象を絞った末端コマンドのヘルプは手軽で、ローカルに確認できます。一方、ルートヘルプはコマンド一覧全体を返すため、トークン効率がよくありません。このスキルですでに説明しているグローバルフラグを確認するだけのために、ルートヘルプを読み込んではいけません。明らかな Docs & Files のリクエストでは、親やルートのヘルプを試す前に、files list、files download、または files uploads create に直接進んでください。サブコマンドの inherited_flags は意図的に簡潔に記載されています。--agent、--jq、--profile、--verbose などのグローバルフラグも、対応している箇所では引き続き使用できます。

必ず守るルール

• OAuth トークンや認証情報ファイルを読み取ったり、表示したり、ログに記録したりしてはいけません。特に、~/.config/basecamp/credentials.json を開いてはいけません。
• JSON を外部の jq にパイプしてはいけません。CLI に組み込まれた --jq を使用してください。
• Basecamp URL の ID を使用する前に、URL を解析してください。 basecamp url parse "<url>" --json。信頼できる Basecamp ホストの URL のみを信用してください。末端コマンドのヘルプで <id|url> が明示的に許可されている読み取り専用コマンドでは、信頼できる URL を直接使用できます。
• コメントはフラットな構造です。返信は親の投稿先に行われ、コメント ID には投稿されません。コメントの URL を受け取った場合、状況の把握に必要であれば comments show または comments thread を使用して reply_target を取得してください。
• プロジェクトのコンテキストを尊重してください。プロジェクトを決めつける前に .basecamp/config.json を確認してください。該当しない場合は --in <project> または末端コマンドのヘルプに表示されるスコープを渡してください。
• エージェントの作業では、非インタラクティブ出力を使用してください。曖昧な選択画面によって実行が妨げられないようにしてください。
• 結果にコンテンツや説明の添付ファイルが含まれている場合は、ダウンロードして内容を確認してください。画像にタスクの重要なコンテキストが含まれていることはよくあります。
• 以前の CLI バージョンの例ではなく、インストール済みコマンドのヘルプに従ってください。

出力モード

目的に応じてモードを選択してください。

目的	モード
データを抽出、集計、または変換する	--jq '<expression>'
構造化された応答全体を使用する	--json
エンベロープなしでデータを使用する	--agent
移植性のある出力を人に直接提示する	--md

--jq を指定すると JSON が有効になります。通常は JSON エンベロープに対してフィルタリングするため、データは一般に .data の下にあります。--agent --jq の場合は、データのみのペイロードに対してフィルタリングされます。人向けの一覧には --md を使用してください。ただし、--md だけではインタラクティブなプロンプトは抑制されません。曖昧さをなくすために十分なスコープを指定するか、BASECAMP_NONINTERACTIVE=1 を設定してください。

コマンドの発見ではなく、一般的な変換の例：

basecamp <leaf-command> --jq '.data | length'
basecamp <leaf-command> --jq '[.data[] | {id, name}]'

プロジェクト、アカウント、ページネーションのスコープ

コマンド名から、そのコマンドがプロジェクト単位かアカウント全体かを推測してはいけません。末端コマンドのヘルプと注記を確認してください。ユーザーがプロジェクトまたはアカウントを明示している場合はそれを使用し、そうでない場合は、信頼できるローカル設定に従ってください。

ページネーションに対応するコマンドでは、ページネーションのフラグを組み合わせる前にヘルプを確認してください。一般に、--limit N は自動ページネーションの結果数を制限し、--all はすべてのページを取得し、--page N は単一のページを要求します。ただし、エンドポイントによって異なる場合があり、互いに排他的な組み合わせは拒否されます。

名前付き ID にはプロファイルを使用します。グローバルな --profile <name> または BASECAMP_PROFILE=<name> で選択してください。プロファイルやデフォルトアカウントを、ユーザーに知らせずに切り替えてはいけません。

URL と返信

解析された URL から account_id、project_id、recording_id を取得できます。また、フラグメントがコメントを指している場合は comment_id も取得できます。

basecamp url parse "https://3.basecamp.com/123/buckets/456/todos/789" --json

返信する場合は、フラグメント ID に投稿するのではなく、返信に必要なコンテキストを取得してください。

basecamp comments thread "<comment-url>" --json
# Post to .data.reply_target.recording_id

返信先とメンションのアトムだけが必要な場合は comments show を、周囲のやり取りも確認したい場合は comments thread を使用してください。

Ping

Ping は、アカウント上の人同士がプロジェクト外で行うプライベートな会話です。ほかの 1 人との 1 対 1 の会話、または複数人でのグループ会話です。プロジェクトのチャットではないため、chat list --all には表示されません。pings グループを使用してください。

basecamp pings list --agent                  # your pings
basecamp pings start "Jane Smith" --agent    # open your ping with Jane, or start it
basecamp pings post "Jane Smith" "Lunch?" --agent
basecamp pings messages "Jane Smith" --agent

• <ping> は Ping ID、Ping の URL（/circles/<id> または /circles/<id>@<line>）、または人を指定します。数字だけの場合は常に Ping ID であり、人の ID ではありません。
• pings list には、メッセージがある Ping が表示されます。開始したばかりの Ping はまだ一覧に表示されませんが、pings start がその Ping を出力します。
• pings start は既存のものを再利用します。各人につき 1 対 1 の Ping が 1 つ、各メンバーの組み合わせにつきグループ Ping が 1 つです（--new-group を指定した場合を除く）。すでにある Ping を見つけるには、これを使用してください。
• pings messages と、人を指定した pings show は、すでにある 1 対 1 の Ping を読み取るだけで、新たに開始することはありません。pings post と pings upload は、Ping がまだない場合に開始します。
• pings post の @メンションは、その Ping に参加している人の中から解決されます。
• メッセージ URL（/circles/<id>@<line>）は basecamp show と chat line で使用できます。その URL を指定して chat update または chat delete を実行すると、メッセージを編集または削除できます。

スポットライト

スポットライトを設定すると、録画のカードがプロジェクトのホームページにある「Spotlights」エリアに表示されます。ピン留めとは異なります。messages pin はメッセージをメッセージボードの上部に固定するだけです。spotlight は、すべての録画タイプのグループ外にあるトップレベルコマンドで、メッセージ、ドキュメント、ファイル、ToDo リスト、ToDo、カード、カード列、チェックインの質問、スケジュール項目などの ID または URL を受け取ります。Basecamp の「Remove Spotlight」と同様に、unspotlight でスポットライトを解除します。

basecamp spotlight <id|url> --agent
basecamp unspotlight <id|url> --agent

プロジェクトの壁紙

壁紙はプロジェクトのページの背景に表示される画像です。projects wallpaper グループを使って設定、レイアウト変更、削除を行います。対象は --in／--project で指定したプロジェクト、または設定済みのデフォルトです。

basecamp projects wallpaper set skyline.jpg --mode tile --in "<project>" --json
basecamp projects wallpaper mode fill --in "<project>" --json
basecamp projects wallpaper remove --in "<project>" --json

• 人と個人用アシスタントには、プロジェクト編集権限が適用されます。共有エージェントは拒否されます（403）。この拒否を再試行したり、回避したりしないでください。
• CLI はアップロード前にファイルサイズと MIME ヒントを確認します。制限は各コマンドのヘルプに記載されています。サーバー側の画像検証も適用されます。--mode は fill または tile です。省略すると現在のモードが維持されます。
• 各コマンドはプロジェクトを返します。.data.wallpaper は {url, mode} で、プロジェクトに壁紙がない場合は含まれません。projects show にも同じフィールドが含まれます。URL へのアクセスには認証が必要で、画像へリダイレクトされます。公開画像リンクではありません。

コンテンツと標準入力

コマンドのヘルプには、コンテンツ引数と標準入力のサポートが記載されています。タイトルは通常プレーンテキストで、リッチテキストフィールドは通常 Markdown を受け付けます。また、ドキュメントに記載されている場合は --format html で HTML を使用できます。ヘルプに位置引数が示されている場合、--title、--body、--content フラグがあると決めつけないでください。

複数行、非 ASCII 文字、またはシェルで特別な扱いが必要なコンテンツを渡すには、ドキュメントに記載されたコンテンツの位置に - を指定し、標準入力をパイプで渡します。

printf '%s\n' 'First line' '' 'Second line' |
  basecamp <leaf-command> <other-args> - --json

パイプが暗黙的に読み取られることはありません。1 回の呼び出しで標準入力を読み取れる入力は 1 つだけです。移植性のあるコマンドでは、$'line 1\nline 2' のようなシェル固有の ANSI-C クォートを使用しないでください。

リッチテキストフィールドは Mermaid の図に対応しています。ソースを mermaid 言語のフェンス付きコードブロックに入れると、Basecamp では投稿を読む人に図が表示されます。プレビュー、メール、エクスポートにはソースが表示されます。また、ソースを解析できない投稿でもソースが表示されます。文章よりも図のほうが分かりやすいフロー、シーケンス、タイムライン、構造には図を使ってください。図のソースは複数行にわたるため、標準入力で渡します。

basecamp messages create "Release flow" - --in "<project>" --json <<'EOF'
How a release reaches production:

```mermaid
flowchart LR
  Merge --> CI --> Staging --> Production
```
EOF

動画、Dash グラフ、その他 Basecamp のエディターでリンクを貼り付けたときに埋め込まれるコンテンツを埋め込むには、Markdown コンテンツ内の単独の行に URL を記述します。CLI は Basecamp に埋め込みを要求し、処理が完了するまで待ちます。Basecamp で埋め込めない URL はリンクのままです。また、文、リスト、引用、コード内の URL も同様です。Basecamp で埋め込み可能なコンテンツへのリンクをそのまま残すには、[title](url) と記述します。

basecamp cards create "Checkout latency" - --in "<project>" --json <<'EOF'
p99 since the deploy:

https://dash.37signals.com/widgets/abc
EOF

--format html を指定した場合、自動では何も埋め込まれません。basecamp embeds create <url> --json を実行し、その attachment タグを HTML に入れてください。

メンションを確実に指定するには、人物やコメントの結果から得られる機械提供のメンション構文（例：[@Name](mention:SGID)）を優先してください。メンションのサポート状況はフィールドによって異なります。各コマンドのヘルプを正としてください。

エラーと復旧

構造化されたエラーには、error、code、retryable、および多くの場合 hint が含まれます。

• retryable が true の場合に限り、上限を設けたバックオフを行って再試行してください。
• retryable: false は、再試行を肯定するシグナルがないことを意味し、既知の判定と未分類の失敗の両方が該当します。復旧方法を決める前に code、error、hint を確認し、同じ呼び出しをむやみに繰り返さないでください。
• 使用方法のエラーが発生した場合は、各コマンドのヘルプを確認し、指定された位置引数を渡してください。
• CLI がコマンドまたはフラグを不明なものとして拒否した場合は、まずグループのヘルプで現在の形式を確認してください。このスキルに記載されているのにヘルプにない場合は、CLI とこのスキルのリリースが異なる可能性があります。basecamp doctor --json で両方のバージョンを確認できます。CLI の場合は basecamp upgrade、プラグインの場合はプラグインの更新と、古いほうをユーザーに伝えてください。
• 名前が曖昧な場合は、ID を使うか、不足しているプロジェクト／コンテナの範囲を指定してください。
• 認証または接続の診断には、認証情報を変更する前に basecamp doctor --json と basecamp auth status --json を使ってください。
• ログインの復旧を行う前に、oauth_type を確認してください。agent プロファイルは、CLI のヒントに記載されたエージェント／クライアント認証情報フローで復旧する必要があります。通常のユーザーログインを行うと、エージェントの ID が置き換わる可能性があります。

コマンドが失敗したという理由だけで、未確認の生 API 呼び出しを即興で行わないでください。まず関連するヘルプとエラーのヒントを確認してください。basecamp api を使うのは、CLI にネイティブな操作がなく、API のパスとペイロードが分かっている場合に限ります。

変更操作

Basecamp を変更する前に、次の手順を実行してください。

1. アカウント、プロジェクト、コンテナ、項目を曖昧さなく特定します。
2. 各コマンドのヘルプを確認し、必須の位置引数と、公開範囲または通知の動作を把握します。
3. 依頼された変更を最小限にとどめます。
4. 結果の ID／URL を返し、変更内容を要約します。

破壊的な操作や広範囲に及ぶ操作では、コマンドにドライランがある場合は実行前にプレビューし、ユーザーが依頼した範囲を広げないでください。