bluesky – OpenClaw Skill

---

name: bluesky version: 1.5.2 description: "Complete Bluesky CLI: post, reply, like, repost, follow, block, mute, search, threads, images. Everything you need to engage on Bluesky from the terminal." homepage: https://bsky.app metadata: openclaw: emoji: "🦋" requires: bins: ["python3"] tags: ["social", "bluesky", "at-protocol", "cli"]

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

🦋 Bluesky CLI

A full-featured command-line interface for Bluesky (AT Protocol). Post, reply, like, repost, follow, block, mute, search — everything you need to engage on Bluesky from your terminal.

Built for OpenClaw — works standalone too.

✨ Features

Category	Commands
Content	post, reply, quote, delete
Engagement	like, unlike, repost, unrepost
Social	follow, unfollow, profile
Moderation	block, unblock, mute, unmute
Discovery	timeline, search, notifications, thread
Media	Image attachments with alt text

Plus: JSON output on all read commands, dry-run mode, auto-linked URLs and @mentions.

🚀 Quick Start

Step 1: Get an App Password from Bluesky

1. Open bsky.app and log in
2. Click your avatar → Settings
3. Go to Privacy and Security → App Passwords
4. Click Add App Password
5. Name it something like "CLI" or "OpenClaw"
6. Copy the password (looks like xxxx-xxxx-xxxx-xxxx)

⚠️ Save this password somewhere safe — Bluesky only shows it once!

Step 2: Login via CLI

Tell your OpenClaw agent:

"Log me into Bluesky. My handle is yourname.bsky.social and my app password is xxxx-xxxx-xxxx-xxxx"

Or run directly:

bsky login --handle yourname.bsky.social --password xxxx-xxxx-xxxx-xxxx

Your password is used once to get a session token, then immediately discarded. It's never stored.

Step 3: Verify & Start Posting

bsky whoami                              # Confirm you're logged in
bsky post "Hello from the command line! 🦋"  # Your first post!

📖 Usage

Posting & Content

bsky post "Hello world!"                              # Simple post
bsky post "Look!" --image pic.jpg --alt "A sunset"    # With image
bsky reply <url> "Great point!"                       # Reply
bsky quote <url> "This is important"                  # Quote-post
bsky delete <url>                                     # Delete your post

Engagement

bsky like <url>          # ❤️ Like a post
bsky unlike <url>        # Remove like
bsky repost <url>        # 🔁 Boost (aliases: boost, rt)
bsky unrepost <url>      # Remove repost

Social

bsky follow @someone.bsky.social    # Follow
bsky unfollow @someone              # Unfollow
bsky profile @someone               # View profile

Moderation

bsky block @troll.bsky.social       # 🚫 Block
bsky unblock @someone               # Unblock
bsky mute @noisy.bsky.social        # 🔇 Mute
bsky unmute @someone                # Unmute

Discovery

bsky timeline                       # Your home feed
bsky timeline -n 30                 # More posts
bsky search "topic"                 # Search posts
bsky notifications                  # Your notifications
bsky thread <url>                   # View conversation

JSON Output

Add --json to any read command for structured output:

bsky timeline --json | jq '.[0].text'
bsky search "AI" --json
bsky notifications --json

🔒 Security

• Password never stored — used once to get a session token, then discarded
• Session tokens auto-refresh — no need to re-login
• Config file permissions — 600 (owner-only read/write)
• Location: ~/.config/bsky/config.json

📦 Installation

For OpenClaw

clawdhub install bluesky

Manual

git clone https://github.com/jeffaf/bluesky-skill.git ~/clawd/skills/bluesky
cd ~/clawd/skills/bluesky/scripts
./bsky --version  # Auto-creates venv on first run

Requirements

• Python 3.8+
• atproto package (installed automatically on first run via venv)

🎯 Tips

• Handles: Auto-appends .bsky.social if no domain specified
• URLs: Both https://bsky.app/... and at:// URIs work
• Dry run: Use --dry-run on post/reply/quote to preview
• Images: Max 1MB, alt text required (accessibility)

📝 Changelog

See CHANGELOG.md for version history.

📄 License

MIT — do whatever you want with it.

---

Made with 🦞 by jeffaf and Mai