bluesky

# 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