social-cli

social-cli

エージェント向けに最適化されたソーシャル CLI。Bluesky + X。YAML を入力し、YAML を出力します。自動化向けの終了コードを備えています。

リポジトリ：https://github.com/letta-ai/social-cli

セットアップ

1. インストール

git clone https://github.com/letta-ai/social-cli.git
cd social-cli
pnpm install
pnpm build

バイナリをグローバルにリンクするか、リポジトリのディレクトリから node dist/cli.js / pnpm start を実行してください。

2. 認証情報

social-cli を実行する作業ディレクトリに .env を作成します。

# Bluesky / ATProto
ATPROTO_HANDLE=you.bsky.social
ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
ATPROTO_PDS=https://bsky.social          # optional, defaults to bsky.social

# X / Twitter (OAuth 1.0a)
X_API_KEY=...
X_API_SECRET=...
X_ACCESS_TOKEN=...
X_ACCESS_TOKEN_SECRET=...
X_BEARER_TOKEN=...                       # optional, for app-only endpoints

実際に使用するプラットフォームの認証情報のみが必要です。

3. 確認

social-cli whoami
social-cli rate-limits

エージェントループ（同期 → 確認 → 送信）

標準的な自動化ワークフローです。各フェーズでは、作業ディレクトリ内の YAML ファイルを読み書きします。

social-cli sync                    # pull notifications → inbox-{platform}.yaml
social-cli check || exit 0         # anything actionable? exit 1 = nothing to do
# read inbox, decide, write outbox-{platform}.yaml
social-cli dispatch                # execute outbox, archive results

• sync：sent_ledger-{platform}.yaml と照合して重複を除外し、受信トレイのサイズを制限します。
• check：受信トレイに対応が必要な項目がある場合は 0、ない場合は 1 で終了します。cron ループでは || exit 0 でラップしてください。
• dispatch：送信トレイをアトミックに実行します。dispatch_result-{platform}.yaml を書き込み、再実行時の重複防止のため sent_ledger-{platform}.yaml に追記します。

クイックコマンド

# Post / reply / thread
social-cli post "Hello world" -p bsky
social-cli reply "Thanks" --id "at://did:plc:.../app.bsky.feed.post/abc" -p bsky
social-cli thread "p1" "p2" "p3" -p bsky

# Engagement
social-cli like "at://..." -p bsky
social-cli delete "at://..." -p bsky
social-cli follow "handle.bsky.social" -p bsky

# Reading
social-cli search "query" -p bsky -n 10              # → stdout YAML
social-cli feed -p bsky -n 20                        # → feed.yaml (or -o - for stdout)
social-cli feed --feed "at://did:.../app.bsky.feed.generator/name" -n 10  # custom feed
social-cli profile "handle.bsky.social" -p bsky
social-cli whoami
social-cli rate-limits

アノテーション（Bluesky のみ）

at.margin.note の語彙（W3C Web Annotation モデル）を使用します。アノテーションは ATProto の投稿に限らず、あらゆる URL で機能します。margin.at と Semble に表示されます。

# Annotate a web page
social-cli annotate "Note about this article" --target https://example.com

# Anchor to an exact passage
social-cli annotate "Key insight" --target https://example.com \
  --quote "exact passage from the page" --motivation highlighting

動機：commenting、highlighting、questioning、describing、linking。

受信トレイ形式（inbox-{platform}.yaml）

notifications:
  - id: "at://did:plc:xxx/app.bsky.feed.post/abc"
    platform: bsky
    type: mention          # mention, reply, like, follow, repost, quote
    author: someone.bsky.social
    authorId: "did:plc:xxx"
    postId: "at://..."
    text: "Hey, what do you think?"
    timestamp: "2026-03-25T12:00:00Z"
    parentPostId: "at://..."     # for replies
    parentPostText: "..."        # context
    rootPostId: "at://..."       # thread root
    rootPostText: "..."

送信トレイ形式（outbox-{platform}.yaml）

判断内容を dispatch リストとして記述します。各エントリは単一のアクションです。

dispatch:
  - reply:
      platform: bsky
      id: "at://did:plc:xxx/app.bsky.feed.post/abc"
      text: "Thanks for the mention"

  - post:
      text: "Hello from my agent"
      platforms: [bsky, x]          # post to both

  - thread:
      platform: bsky
      posts:
        - "Thread post 1"
        - "Thread post 2"

  - like:
      platform: bsky
      id: "at://..."

  - annotate:
      platform: bsky
      id: "https://example.com/article"
      text: "Key observation"
      motivation: commenting
      quote: "exact text to anchor to"

  - ignore:
      id: "notif_003"
      reason: "spam"

送信結果と終了コード

dispatch_result-{platform}.yaml は送信のたびに書き込まれます。終了コード：

コード	意味
0	すべてのアクションが成功
1	無効な送信トレイ（スキーマエラー、認証情報の不足）
2	部分的な失敗（一部は成功し、一部は失敗）

スレッドの送信に失敗した場合は、インデックスと残りの投稿を含む resumeFrom フィールドが出力されるため、残りの投稿だけを再試行できます。

文字数制限

プラットフォーム	制限
Bluesky	300 文字
X	280 文字

CLI は API に送信する前に、制限を超える投稿を拒否します。

プラットフォーム間の違い

機能	Bluesky	X
アノテーション（at.margin.note）	はい	いいえ
検索	はい	はい
フィード	はい（カスタムフィード）	はい（ホーム／ユーザー）
スレッド	はい	はい
通知	メンション、返信、いいね、フォロー、リポスト、引用	メンションのみ
引用投稿のコンテキスト	はい	はい

耐障害性

• 429、5xx、ネットワークエラーの場合、指数バックオフを使用して 3 回再試行します。Retry-After に従います。
• Bluesky のセッションはトークンの有効期限切れ時に自動更新されます。
• ファイルへのアトミックな書き込み（tmp + rename）により、受信トレイ／送信トレイが不完全な状態になるのを防ぎます。
• 部分的な失敗時は resumeFrom を使ってスレッドの続きを再開できます。
• sent_ledger-{platform}.yaml により、実行をまたいだ送信の重複を防止します。

作業ディレクトリの構成

すべてが現在の作業ディレクトリ内に収まるため、状態を分離して複数のエージェントを実行できます。

./
├── .env
├── inbox-bsky.yaml          # sync output
├── inbox-x.yaml
├── outbox-bsky.yaml         # your decisions
├── outbox-x.yaml
├── dispatch_result-bsky.yaml  # last dispatch outcome
├── dispatch_result-x.yaml
├── sent_ledger-bsky.yaml      # replay protection
├── sent_ledger-x.yaml
└── feed.yaml                  # optional feed snapshots

参考資料

• references/commands.md：すべてのフラグを含むコマンド一覧
• references/outbox-schema.md：送信トレイの YAML スキーマ全体
• references/agent-loop.md：cron／systemd 自動化ループのパターン