Introduction
# 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>` | | 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 ```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 ```
### Create Thread ```bash 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 ```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