atpcli 0.5.0

A Python CLI wrapper around the atproto package

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:

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

Note: When using special characters like !, use single quotes to avoid shell expansion issues. 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