Bluesky CLI

Full-featured CLI for Bluesky/AT Protocol.

Agent Instructions

First: Check if logged in

bsky whoami

• If shows handle → ready to use commands below
• If "Not logged in" → guide user through Setup section

Common tasks:

• "Post to Bluesky" → bsky post "text"
• "Check my timeline" → bsky timeline
• "Like this post" → bsky like <url>
• "Follow someone" → bsky follow @handle

Setup

If user isn't logged in (bsky whoami shows "Not logged in"), guide them through setup:

Getting an App Password

Tell the user:

> Go to bsky.app → click your avatar → Settings → Privacy and Security → App Passwords → Add App Password. Name it "OpenClaw" and copy the password (like xxxx-xxxx-xxxx-xxxx). You'll only see it once!

Logging In

Once they have the app password, run:

bsky login --handle THEIR_HANDLE.bsky.social --password THEIR_APP_PASSWORD

Example:

bsky login --handle alice.bsky.social --password abcd-1234-efgh-5678

Security: Password is used once to get a session token, then immediately discarded. Never stored on disk. Session auto-refreshes.

Quick Reference

| Action | Command |

|--------|---------|

| View timeline | bsky timeline or bsky tl |

| Post | bsky post "text" |

| Post with image | bsky post "text" --image photo.jpg --alt "description" |

| Reply | bsky reply <url> "text" |

| Quote-post | bsky quote <url> "text" |

| View thread | bsky thread <url> |

| Create thread | bsky create-thread "Post 1" "Post 2" "Post 3" or bsky ct |

| Like | bsky like <url> |

| Repost | bsky repost <url> |

| Follow | bsky follow @handle |

| Block | bsky block @handle |

| Mute | bsky mute @handle |

| Search | bsky search "query" |

| Notifications | bsky notifications or bsky n |

| Delete post | bsky delete <url> |

Commands

Timeline

bsky timeline              # 10 posts
bsky timeline -n 20        # 20 posts
bsky timeline --json       # JSON output

Posting

bsky post "Hello world!"                           # Basic post
bsky post "Check this!" --image pic.jpg --alt "A photo"  # With image
bsky post "Test" --dry-run                         # Preview only

Reply & Quote

bsky reply <post-url> "Your reply"
bsky quote <post-url> "Your take on this"

Thread View

bsky thread <post-url>           # View conversation
bsky thread <url> --depth 10     # More replies
bsky thread <url> --json         # JSON output

Create Thread

bsky create-thread "First post" "Second post" "Third post"   # Create a thread
bsky ct "Post 1" "Post 2" "Post 3"                           # Short alias
bsky create-thread "Hello!" "More thoughts" --dry-run         # Preview only
bsky create-thread "Look!" "Nice" --image pic.jpg --alt "A photo"  # Image on first post

Engagement

bsky like <post-url>             # ❤️ Like
bsky unlike <post-url>           # Remove like
bsky repost <post-url>           # 🔁 Repost (aliases: boost, rt)
bsky unrepost <post-url>         # Remove repost

Social Graph

bsky follow @someone             # Follow user
bsky unfollow @someone           # Unfollow user
bsky profile @someone            # View profile
bsky profile --json              # JSON output

Moderation

bsky block @someone              # 🚫 Block user
bsky unblock @someone            # Unblock
bsky mute @someone               # 🔇 Mute user
bsky unmute @someone             # Unmute

Search & Notifications

bsky search "query"              # Search posts
bsky search "topic" -n 20        # More results
bsky notifications               # Recent notifications
bsky n -n 30                     # More notifications

Delete

bsky delete <post-url>           # Delete your post
bsky delete <post-id>            # By ID

JSON Output

Add --json to read commands for structured output:

bsky timeline --json
bsky search "topic" --json
bsky notifications --json
bsky profile @someone --json
bsky thread <url> --json

Error Handling

| Error | Fix |

|-------|-----|

| "Session expired" | Run bsky login again |

| "Not logged in" | Run bsky login --handle ... --password ... |

| "Post is X chars (max 300)" | Shorten text |

| "Image too large" | Use image under 1MB |

Notes

• All <url> parameters accept either https://bsky.app/... URLs or at:// URIs
• Handles auto-append .bsky.social if no domain specified
• Image posts require --alt for accessibility (Bluesky requirement)
• Session tokens auto-refresh; password never stored