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 show --json を実行してください。その project_id は、フラグ、環境変数、すべての設定レイヤーを反映した実効値と、その値の取得元を示します。.basecamp/config.json を直接読み込まないでください。これは設定レイヤーのひとつにすぎません。project_id がない場合は、--in <project> またはリーフのヘルプに記載されたスコープを指定してください。
• エージェントの処理では非対話型の出力を使用してください。曖昧な選択メニューによって実行が妨げられないようにしてください。
• 結果にコンテンツの添付ファイルや説明の添付ファイルが示された場合は、ダウンロードして内容を確認してください。画像にタスクの重要なコンテキストが含まれていることがよくあります。
• アイテムを別のコンテナに移動すると、新しい ID が表示されます。移動後は古い ID では書き込みできなくなるため、新しい ID を使用してください。コピーすると、元のアイテムはそのまま残り、コピーの ID が表示されます。コピーは絶対に繰り返さないでください。Basecamp はバックグラウンドでファイルを処理するため、コピーの処理中、または結果を受け取れなかった場合でも、すでにコピーが存在している可能性があります。コピーを繰り返すのではなく、basecamp filings show <id> コマンド、または表示されたヒントで確認してください。
• 以前の 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 は1ページを要求します。ただし、エンドポイントによって動作が異なる場合があり、併用できない組み合わせは拒否されます。

名前付きの 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 を使用してください。

Pings

ping は、プロジェクト外でアカウント上の人々が行うプライベートな会話です。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 は既存のものを再利用します。つまり、人物ごとに直接 ping を1つ、人物の組み合わせごとにグループを1つ再利用します（--new-group を指定した場合を除く）。すでにある ping を見つけるには、これを使用してください。
• 人物を指定した pings messages と pings show は、すでにある直接 ping を読み取るだけで、新たに開始することはありません。pings post と pings upload は、直接 ping が存在しない場合に開始します。
• pings post の @メンションは、その ping に参加している人物の中から解決されます。
• メッセージ URL（/circles/<id>@<line>）は basecamp show と chat line で使用できます。この URL を指定して chat update または chat delete を実行すると、そのメッセージを編集または削除できます。
• 一般的な recording コマンドでは、ping の内容は変更できません。recordings trash、archive、restore、visibility、subscriptions add、remove、spotlight は拒否されます（終了コード 4）。変更できるのは自身のサブスクリプションだけで、その場合は subscriptions subscribe または subscriptions unsubscribe を使用してください。

Spotlights

spotlight を設定すると、プロジェクトのホームページにある Spotlights エリアに recording のカードが表示されます。ピン留めとは異なります。messages pin は、メッセージを Message Board の最上部に表示し続けるだけです。spotlight は recording の種類別グループの外にあるトップレベルコマンドで、メッセージ、ドキュメント、ファイル、to-do リスト、to-do、カード、カード列、チェックインの質問、スケジュール項目などの ID または URL を受け取ります。unspotlight はこれを削除します。Basecamp の「Remove Spotlight」と同じ操作です。

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 の利用には認証が必要で、画像にリダイレクトされます。公開画像リンクではありません。

プロジェクトのロゴ

ロゴはプロジェクト名の横に表示される画像で、壁紙とは別のものです。 projects logo グループを使うと、--in／--project で指定したプロジェクト、または設定済みのデフォルトプロジェクトのロゴを設定または削除できます。

basecamp projects logo set brand.png --in "<project>" --json
basecamp projects logo remove --in "<project>" --json

• プロジェクトを編集できるユーザーやエージェントは、ロゴを変更できます。それ以外のユーザーには 403 が返され、呼び出し元が表示できないプロジェクトには 404 が返されます。どちらの拒否についても、再試行したり回避したりしないでください。
• CLI はアップロード前に、ファイルサイズと MIME ヒントを確認します。各コマンドのヘルプには制限が記載されています。サーバー側の画像検証も適用されます。ロゴのないプロジェクトからロゴを削除しても、処理は成功します。
• 各コマンドはプロジェクトを返します。.data.logo は {url} で、プロジェクトにロゴがない場合は存在しません。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呼び出しを即興で行わないでください。まず該当するヘルプとエラーのヒントを確認します。CLIにネイティブの操作がなく、APIのパスとペイロードが分かっている場合に限り、basecamp apiを使います。

変更操作

Basecampを変更する前に、次の手順を実行します。

1. アカウント、プロジェクト、コンテナ、項目を曖昧さなく特定します。
2. 必須の位置引数と、表示や通知の動作について、該当するコマンドのヘルプを確認します。
3. 依頼された内容に必要な最小限の変更を行います。
4. 結果のID／URLを返し、変更内容を要約します。

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