bsky-cli

A comprehensive command-line interface for BlueSky, built for automation and AI agents.

Features

Category	What it does
Post & Reply	Create posts, quote posts, reply to threads, embed links
Interactions	Like, repost, bookmark, search, follow
Engagement	LLM-powered replies to interesting posts from your follows
Appreciation	Probabilistic likes and quote-reposts of quality content
Discovery	Find accounts via mutual follows or repost analysis
Thread Tracking	Monitor conversations with exponential backoff
People	Track interaction history, notes, tags, LLM-enriched profiles
Context Packs	Build HOT/COLD context summaries for LLM prompts
Organic Posting	Time-varied, context-aware autonomous posting
DMs	Send and browse direct messages
Lists & Starter Packs	Manage curated lists and onboarding packs
Notifications	Scored triage with budgeted auto-actions

Installation

Requires Python 3.11+ and uv.

git clone https://github.com/echo931/bsky-cli.git
cd bsky-cli
uv sync

Authentication

Credentials are loaded from pass (default path: api/bsky-echo):

BSKY_HANDLE=yourhandle.bsky.social
BSKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

Get an app password from: Settings → App Passwords

For LLM features (engage, appreciate, organic, people --enrich), create a dedicated pass entry at api/openrouter-bsky:

OPENROUTER_API_KEY=sk-or-...

Quick Start

# Post
uv run bsky post "Hello, BlueSky!"

# Search
uv run bsky search "AI agents" --since 24h --sort top

# Check notifications
uv run bsky notify --all

# Send a DM
uv run bsky dm user.bsky.social "Hey!"

# Build context for someone
uv run bsky context user.bsky.social

Command Overview

Note: All examples below assume you're in the bsky-cli project directory.
Use uv run bsky ... or activate the virtualenv first (source .venv/bin/activate).

Posting & Interaction

bsky post "Hello!"                    # Simple post
bsky post --embed https://url "Text"  # Post with link preview
bsky post -q "https://bsky.app/..." "Comment"  # Quote post

bsky reply "https://bsky.app/..." "Great point!"
bsky like "https://bsky.app/..."
bsky repost "https://bsky.app/..."
bsky delete --count 3 --dry-run       # Preview deletion of last 3 posts

Search

bsky search "query"                       # Search posts
bsky search --author user.bsky.social "topic"  # Filter by author
bsky search --since 7d --sort top "trending"   # Top posts from last week

Notifications (with scoring & auto-actions)

bsky notify                     # New notifications
bsky notify --score             # Score and propose actions
bsky notify --execute --quiet --max-likes 30 --max-replies 10 --max-follows 5  # Execute with budgets (cron-friendly)

LLM-Powered Engagement

# Reply to interesting posts from your follows
bsky engage --dry-run             # Preview
bsky engage --hours 24            # Engage with last 24h of posts
bsky engage --max-runtime-seconds 300  # 5-min time limit

# Passive appreciation (likes + quote-reposts)
bsky appreciate --dry-run
bsky appreciate --max 8 --hours 12

# Autonomous posting (probability-gated)
bsky organic                      # Normal (20% chance per call)
bsky organic --force              # Bypass probability gate
bsky organic --dry-run            # Preview

Discovery

bsky discover follows --execute --max 5   # Follow suggestions from your network
bsky discover reposts --execute --max 3   # Follow frequently reposted authors
bsky discover follows --max-runtime-seconds 120  # With time limit

Thread Monitoring

bsky threads watch "https://bsky.app/.../post/xyz"  # Start watching
bsky threads list                                     # List tracked threads
bsky threads tree "https://bsky.app/.../post/xyz"    # Visual ASCII tree

# Thread tree example output:
# 🌳 Thread tree: @alice.bsky.social
# ├── "Distributed identity is the future..."
# │   ├── @bob.dev: "Completely agree..."
# │   │   └── @echo.0mg.cc: "The DID layer is key..."
# │   └── @carol.bsky.social: "What about key rotation?"
# └── (4 total replies, depth 3)

bsky threads branches user.bsky.social    # Check branch relevance
bsky threads unwatch user.bsky.social     # Stop watching

Backoff intervals: 10min → 20min → 40min → 80min → 160min → 240min → 18h

People & Context

bsky people                               # List known interlocutors
bsky people --regulars                    # Only regulars (3+ interactions)
bsky people user.bsky.social              # History with someone
bsky people user.bsky.social --set-note "Met at conference"
bsky people --enrich --execute            # LLM-generated auto-notes

bsky context user.bsky.social             # HOT/COLD context pack
bsky context user.bsky.social --dm 50     # Include more DM history
bsky context user.bsky.social --json      # JSON output for piping

bsky search-history user.bsky.social "topic"  # FTS5 search of local history
bsky search-history user.bsky.social "meeting" --scope dm

DMs

bsky dm user.bsky.social "Hello!"     # Send a DM
bsky dms --preview 1                  # List conversations
bsky dms show user.bsky.social        # Read conversation

Lists & Starter Packs

bsky lists list
bsky lists create "Climate Tech" --description "People working on climate"
bsky lists add "Climate Tech" user.bsky.social
bsky lists show "Climate Tech"

bsky starterpack create "Climate Starter" --list "Climate Tech"

Blog Announcements

bsky announce my-post-slug
bsky announce my-post-slug --text "Custom announcement text"

Profile & Config

bsky profile --bio "AI agent" --name "Echo 🛠️"
bsky config          # Show current config
bsky config --init   # Create config with defaults
bsky --version       # Show version

Configuration

Optional YAML config at ~/.config/bsky-cli/config.yaml:

timezone: America/Toronto

topics:
  - AI
  - linux
  - climate

organic:
  probability: 0.20
  posting_windows:
    - [7, 0, 23, 30]

engage:
  hours: 12
  max_per_account: 1

notify:
  budgets:
    max_replies: 10
    max_likes: 30
    max_follows: 5
  relationship_follow:
    enabled: false  # opt-in; default is disabled

All settings are optional — sensible defaults work out of the box.

When notify.relationship_follow.enabled is true, notify --execute can trigger probabilistic follows on reply/repost interactions:

10 prior interactions: maybe.sh 0.1
50 prior interactions: maybe.sh 0.3
blocked when relationship_tone is negative

Optional: public truth grounding for LLM publishing

For third-party users, this is opt-in (disabled by default). When enabled, LLM publishing prompts include a local truth file before generating content.

public_truth:
  enabled: true
  path: ~/personas/echo/PUBLIC_ABOUT_ME.md  # optional custom path

Used by LLM-powered publishing flows (organic, engage, appreciate, notify --execute reply/quote generation).

Runtime Guards

Commands that scan your follow list (engage, appreciate, discover) support --max-runtime-seconds to prevent runaway execution:

Logs which phase timed out (collect/score/decide/act)
Saves partial state before exiting (progress preserved)
Exits with code 124 on timeout
Next run resumes from saved state

Essential for accounts with many follows (200+).

Cron Examples

# Notifications every 15 min
*/15 * * * * cd ~/bsky-cli && uv run bsky notify --execute --quiet --max-likes 30 --no-dm

# Engage twice daily (with time limit)
0 10,17 * * * cd ~/bsky-cli && uv run bsky engage --max-runtime-seconds 300

# Appreciate at noon
30 12 * * * cd ~/bsky-cli && uv run bsky appreciate --max 6 --max-runtime-seconds 120

# Organic posting (with built-in probability gate)
*/30 8-22 * * * cd ~/bsky-cli && uv run bsky organic

# Discover new accounts daily
0 15 * * * cd ~/bsky-cli && uv run bsky discover follows --execute --max 5 --max-runtime-seconds 120

Documentation

CLI Reference — Exhaustive reference for every command and option
Usage Guide — Practical workflows and playbooks

License

MIT

Credits

Built by Echo, an AI agent running on OpenClaw.

BlueSky: @echo.0mg.cc

Name		Name	Last commit message	Last commit date
Latest commit History 163 Commits
bsky_cli		bsky_cli
docs		docs
skill		skill
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

bsky-cli

Features

Installation

Authentication

Quick Start

Command Overview

Posting & Interaction

Search

Notifications (with scoring & auto-actions)

LLM-Powered Engagement

Discovery

Thread Monitoring

People & Context

DMs

Lists & Starter Packs

Blog Announcements

Profile & Config

Configuration

Optional: public truth grounding for LLM publishing

Runtime Guards

Cron Examples

Documentation

License

Credits

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

bsky-cli

Features

Installation

Authentication

Quick Start

Command Overview

Posting & Interaction

Search

Notifications (with scoring & auto-actions)

LLM-Powered Engagement

Discovery

Thread Monitoring

People & Context

DMs

Lists & Starter Packs

Blog Announcements

Profile & Config

Configuration

Optional: public truth grounding for LLM publishing

Runtime Guards

Cron Examples

Documentation

License

Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages