Bluesky
Verified@jeffaf
npx machina-cli add skill @jeffaf/bluesky --openclawBluesky 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 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
Overview
Bluesky CLI is a full-featured command-line interface for Bluesky using the AT Protocol. It enables posting, replying, liking, reposting, following, and managing blocks or mutes from the terminal. This makes Bluesky engagement fast and scriptable in headless or remote environments.
How This Skill Works
The tool checks login status with bsky whoami and guides you through setup if needed (App Password and login). Once authenticated, you run commands like bsky post, bsky timeline, bsky like, and bsky follow to perform actions. Each command maps to Bluesky endpoints and can output text or JSON for automation.
When to Use It
- You are on a headless server or in a script and want to post or engage on Bluesky from the terminal.
- You need to quickly read your Bluesky timeline without a browser.
- You want to like, repost, or reply to a post using its URL.
- You manage your social graph by following, unfollowing, blocking, or muting users.
- You want to search posts or inspect a thread directly from the command line.
Quick Start
- Step 1: Run bsky whoami to verify you are logged in.
- Step 2: If not logged in, complete the Setup steps to obtain an App Password and run bsky login.
- Step 3: Try a common task, e.g., bsky timeline or bsky post "Hello world!"
Best Practices
- Use dry-run for previews before posting to avoid mistakes.
- Prefer --json for automation-friendly output.
- Keep App Passwords secure and understand session tokens are discarded after use.
- Validate URLs and post content to avoid unintended actions.
- Leverage image and thread options to provide richer posts and context.
Example Use Cases
- View timeline: bsky timeline
- Post with image: bsky post "Hello" --image photo.jpg --alt "A photo"
- Like a post: bsky like <url>
- Create a thread: bsky create-thread "First" "Second" "Third"
- Block a user: bsky block @someone
