Bluesky Account Management

Operate a Bluesky social media account via ./bsky <command> [args]. All output is JSON. Run from the project root.

Setup

Install dependencies:

pip install atproto python-dotenv

Requires .env at project root:

BLUESKY_HANDLE=your-handle.bsky.social
BLUESKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

App passwords: https://bsky.app/settings/app-passwords. For DMs, enable "Allow access to your direct messages".

Auth is automatic. A session cache is stored at ~/.bsky_session.json (contains an exported session token). Delete this file to force re-authentication or when revoking access.

JSON Output

Every command prints one JSON object to stdout. Parse with json.loads().

Response Schemas

Post object (returned by get, and inside arrays from timeline, search-posts, my-posts, thread):

{
  "uri": "at://did:plc:abc/app.bsky.feed.post/xyz",
  "cid": "bafyrei...",
  "author": {"handle": "alice.bsky.social", "did": "did:plc:abc", "display_name": "Alice", "avatar": "https://..."},
  "text": "Post content here",
  "created_at": "2026-03-14T10:00:00Z",
  "like_count": 5, "repost_count": 2, "reply_count": 1,
  "viewer": {"liked": "at://...like-uri or null", "reposted": "at://...repost-uri or null"},
  "embed": {"images": [{"alt": "...", "thumb": "...", "fullsize": "..."}], "external": {"uri": "...", "title": "...", "description": "..."}, "record": {"uri": "...", "text": "...", "author": {...}}} or null,
  "reply": {"parent_uri": "at://...", "root_uri": "at://..."} // only present on replies
}

Profile object (returned by profile, and inside arrays from search-users):

{
  "handle": "alice.bsky.social", "did": "did:plc:abc",
  "display_name": "Alice", "description": "Bio text", "avatar": "https://...",
  "followers_count": 100, "follows_count": 50, "posts_count": 200,
  "viewer": {"following": "at://...or null", "followed_by": "at://...or null", "blocking": null, "blocked_by": null, "muted": null}
}

Actor object (short profile, inside post authors, follower/following lists, notification authors):

{"handle": "alice.bsky.social", "did": "did:plc:abc", "display_name": "Alice", "avatar": "https://..."}

Notification object (inside array from notifications):

{
  "reason": "reply|like|repost|follow|mention|quote",
  "uri": "at://...", "cid": "bafyrei...", "is_read": false,
  "indexed_at": "2026-03-14T10:00:00Z",
  "author": {"handle": "...", "did": "...", "display_name": "...", "avatar": "..."},
  "record_text": "Their reply/post text (if applicable)",
  "reason_subject": "at://...the post they liked/reposted/replied-to (if applicable)",
  "subject_text": "Text of the subject post (if reason_subject exists)"
}

Conversation object (inside array from dm-list):

{
  "id": "convo-id", "unread_count": 2,
  "members": [{"handle": "...", "did": "...", "display_name": "...", "avatar": "..."}],
  "last_message": {"id": "msg-id", "text": "...", "sent_at": "...", "sender_did": "did:plc:..."} or null
}

DM message object (inside array from dm-read):

{"id": "msg-id", "text": "Message text", "sent_at": "2026-03-14T10:00:00Z", "sender_did": "did:plc:..."}

Feed object (inside array from feeds):

{
  "uri": "at://did:plc:abc/app.bsky.feed.generator/whats-hot",
  "cid": "bafyrei...", "did": "did:web:...",
  "creator": {"handle": "...", "did": "...", "display_name": "...", "avatar": "..."},
  "display_name": "What's Hot", "description": "Trending posts across Bluesky",
  "avatar": "https://...", "like_count": 12345, "indexed_at": "2026-03-14T10:00:00Z"
}

Command Response Keys

Each command returns these top-level keys:

Important: Note that timeline wraps posts in feed[].post (with an optional reason), while search-posts and my-posts use posts[] directly.

Pagination

List commands support --cursor TOKEN. The response includes "cursor" (null = no more results).

1. First call: omit --cursor
2. Next page: pass the returned cursor as --cursor
3. Stop when cursor is null

Errors

Errors return JSON with exit code 1:

{"error": "ERROR_TYPE", "message": "Human-readable description", "type": "SUBTYPE (for AUTH_ERROR)"}

Error types: NOT_FOUND, NOT_LIKED, NOT_REPOSTED, NOT_FOLLOWING, NOT_BLOCKING, FILE_NOT_FOUND, INVALID_ARGS, AUTH_ERROR.

Command Quick Reference

Posting

Engagement

Reading & Discovery

Social Graph

Profile & Info

Notifications

Direct Messages

Only text DMs are supported (no images).

Common Workflows

Check and respond to mentions

./bsky notifications --unread-only --filter mention
# Parse → for each notification, extract reason_subject (the post they mentioned you in)
./bsky get <reason_subject_uri>
# Read context, then reply:
./bsky post "Your reply" --reply-to <uri>
./bsky notif-read

Engage with timeline

./bsky timeline --limit 30
# Parse → extract feed[].post objects
# Like interesting posts:
./bsky like <uri>
# Reply to engage:
./bsky post "Your reply" --reply-to <uri>

Search and engage with a topic

./bsky search-posts "topic keywords" --limit 20
# Parse → like/repost/reply to relevant posts[]
./bsky like <uri>
./bsky repost <uri>

Join a conversation (read thread before replying)

./bsky thread <uri> --depth 6
# Parse → read thread.text and thread.replies[] to understand context
./bsky post "Informed reply" --reply-to <uri>

Grow the network

./bsky search-users "topic or niche" --limit 20
# Parse → review actors[] profiles for relevance
./bsky profile <handle>
# Check their posts before following:
./bsky user-posts <handle> --limit 10
# Avoid re-following — check viewer.following is null, then:
./bsky follow <handle>

Check engagement on own posts

./bsky my-posts --limit 10
# Parse → find posts with high reply_count
./bsky thread <uri>
# Respond to replies, like engaged followers
./bsky likes <uri>

Check and respond to DMs

./bsky dm-list
# Parse → find conversations[] with unread_count > 0
./bsky dm-read --convo-id <id>
# Parse → read messages[], reply:
./bsky dm-send <handle> "Your reply"
./bsky dm-mark-read --convo-id <id>

Post a thread

./bsky post-thread "First, let me explain the context..." "Second, here's the main point..." "Finally, the conclusion."
# Returns: {"posts": [{"uri": "...", "cid": "..."}, ...]}

Update your profile

./bsky update-profile --name "New Display Name" --bio "Updated bio text"
./bsky update-profile --avatar new-avatar.jpg

Discover feeds

./bsky feeds --limit 10
# Filter by keyword:
./bsky feeds --query "news"

Check before posting (avoid duplicates)

./bsky my-posts --limit 5
# Parse → check posts[].text for similar content
./bsky post "New post text"

Key Concepts

• Handles: Always pass handles without the @ prefix — use user.bsky.social, not @user.bsky.social.
• URIs: Every post has an AT Protocol URI (at://did:plc:abc/app.bsky.feed.post/xyz). Extract from the uri field in JSON. Used as arguments for like, reply, repost, thread, get, delete.
• Rich text: @mentions, #hashtags, URLs in post text are auto-converted to links. Write naturally.
• Character limit: 300 graphemes per post.
• Unlike/unrepost: Pass the post URI, not the like/repost record URI. Auto-resolved internally.
• Reply threading: --reply-to <uri> auto-resolves the thread root.

Auth Troubleshooting

Auth errors: {"error": "AUTH_ERROR", "type": "<TYPE>", "message": "..."} with exit code 1.

1. SESSION_CORRUPT → rm ~/.bsky_session.json and retry
2. MISSING_ENV → Ensure .env has BLUESKY_HANDLE and BLUESKY_APP_PASSWORD
3. INVALID_CREDENTIALS → Handle: user.bsky.social, App password: xxxx-xxxx-xxxx-xxxx (19 chars)
4. NETWORK → Retry up to 3 times with 10s delay
5. ACCOUNT_SUSPENDED → Inform user, cannot fix programmatically