Bluesky CLI

Full-featured CLI for Bluesky/AT Protocol.

Agent Instructions

First: Check if logged in

bash

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:

bash

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

Example:

bash

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

bash

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

Posting

bash

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

bash

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

Thread View

bash

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

Engagement

bash

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

bash

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

Moderation

bash

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

Search & Notifications

bash

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

Delete

bash

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

JSON Output

Add --json to read commands for structured output:

bash

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