bluesky

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>
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

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