atpcli

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:

make docs-serve

Quick Start

Installation

Install globally using uv:

uv tool install atpcli

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):

atpcli login

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:

atpcli bsky 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:

atpcli bsky post

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:

atpcli bsky 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

make install

Run tests

make test

Build documentation

make docs-build

Serve documentation locally

make docs-serve

Format code

make format

Clean build artifacts

make clean

Requirements

• Python 3.10+
• uv package manager

License

MIT