A Python CLI wrapper around the atproto package for interacting with Bluesky.

Documentation

Full documentation is available at docs/:

• Installation Guide
• Quick Start Guide - Learn how to get app passwords and use atpcli
• Login Command
• Timeline Command
• Feeds Commands - List and view custom Bluesky feeds
• Post Command

Or serve the docs locally:

Quick Start

Installation

Install globally using uv:

This installs atpcli as a global tool, making it available from anywhere in your terminal.

Or for development:

git clone https://github.com/phalt/atpcli.git
cd atpcli
make install

Usage

Login

⚠️ Security Note: Use app passwords, not your main password! See the Quick Start Guide for instructions on creating an app password.

Login to an AT Protocol PDS (defaults to Bluesky):

Or login to a custom PDS:

atpcli login https://my-pds.com

You'll be prompted for your handle and password. The session will be saved to ~/.config/atpcli/config.json.

View Timeline

View your timeline:

Options:

• --limit N - Show N posts (default: 10)
• --p N - Show page N (default: 1)

Example:

atpcli bsky timeline --limit 20
atpcli bsky timeline --p 2

Post Messages

Create a post on Bluesky using the interactive editor:

Or post directly with a message:

atpcli bsky post --message 'Hello, Bluesky!'

Note: When using special characters like !, use single quotes to avoid shell expansion issues, or use the interactive editor mode. See the Post Command documentation for more details.

Custom Feeds

List your saved Bluesky feeds:

View posts from a specific feed:

atpcli bsky feed at://did:plc:xxx/app.bsky.feed.generator/discover

Options:

• --limit N - Show N posts (default: 10)
• --p N - Show page N (default: 1)
• --format uri - Output only URIs (for feeds command)

Example:

# List feeds in URI format for scripting
atpcli bsky feeds --format uri

# View a feed with more posts
atpcli bsky feed at://did:plc:xxx/app.bsky.feed.generator/tech --limit 20

# Navigate to page 2
atpcli bsky feed at://did:plc:xxx/app.bsky.feed.generator/tech --p 2

See the Feeds Commands documentation for more details.

Development

Setup

Run tests

Build documentation

Serve documentation locally

Format code

Clean build artifacts

Requirements

• Python 3.10+
• uv package manager

License

MIT