Skill

social-cli

Name: social-cli
Author: Letta

manage social media posts and feeds

Published by Letta Updated Jul 13

Covers Automation CLI Social Media Messaging

Description

Agent-optimized CLI for Bluesky (ATProto) and X (Twitter). YAML in, YAML out, exit codes for automation. Use when the task involves posting, replying, reading feeds, searching, annotating URLs, or running a sync/check/dispatch agent loop across social platforms.

SKILL.md

Agent-optimized social CLI. Bluesky + X. YAML in, YAML out, exit codes for automation.

Repo: https://github.com/letta-ai/social-cli

Setup

1. Install

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

Link the binary globally or invoke via node dist/cli.js / pnpm start from the repo directory.

2. Credentials

Create a .env in the working directory where you run social-cli:

# 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

Only credentials for platforms you actually use are required.

3. Verify

social-cli whoami
social-cli rate-limits

Agent loop (sync → check → dispatch)

The canonical automation workflow. Each phase reads/writes YAML files in the working directory.

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: deduplicates against sent_ledger-{platform}.yaml and caps inbox size.
check: exits 0 if inbox has actionable items, 1 otherwise. Wrap with || exit 0 in cron loops.
dispatch: executes the outbox atomically. Writes dispatch_result-{platform}.yaml and appends to sent_ledger-{platform}.yaml for replay protection.

Quick commands

# 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

Annotations (Bluesky only)

Uses the at.margin.note lexicon (W3C Web Annotation model). Annotations work on any URL, not just ATProto posts. They appear in margin.at and 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

Motivations: commenting, highlighting, questioning, describing, linking.

Inbox format (`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 format (`outbox-{platform}.yaml`)

Write decisions as a dispatch list. Each entry is a single action.

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 results and exit codes

dispatch_result-{platform}.yaml is written after every dispatch. Exit codes:

Code	Meaning
0	All actions succeeded
1	Invalid outbox (schema error, missing creds)
2	Partial failure (some succeeded, some failed)

Thread failures include a resumeFrom field with the index and remaining posts so you can retry just the tail.

Character limits

Platform	Limit
Bluesky	300 chars
X	280 chars

The CLI rejects over-limit posts before hitting the API.

Platform differences

Feature	Bluesky	X
Annotations (`at.margin.note`)	Yes	No
Search	Yes	Yes
Feed	Yes (custom feeds)	Yes (home/user)
Threads	Yes	Yes
Notifications	mention, reply, like, follow, repost, quote	mentions only
Quote post context	Yes	Yes

Resilience

Retries 3x with exponential backoff on 429s, 5xx, and network errors. Respects Retry-After.
Bluesky session auto-refreshes on token expiry.
Atomic file writes (tmp + rename) — no partial inbox/outbox corruption.
Thread resume on partial failure via resumeFrom.
sent_ledger-{platform}.yaml prevents duplicate dispatch across runs.

Working directory layout

Everything is scoped to your current working directory, so you can run multiple agents with isolated state:

./
├── .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

references/commands.md: full command map with all flags
references/outbox-schema.md: complete outbox YAML schema
references/agent-loop.md: patterns for cron/systemd automation loops

More skills from the skills repository

View all 45 skills

SkillTagsUpdated

More from Letta

View publisher

SkillTagsUpdated