Demerzels-lab 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 eitherhttps://bsky.app/...URLs orat://URIs - Handles auto-append
.bsky.socialif no domain specified - Image posts require
--altfor accessibility (Bluesky requirement) - Session tokens auto-refresh; password never stored