activitypub-cli 0.4.0

Command-line client for the ActivityPub API

ap

ap is a command-line client for the ActivityPub protocol.

Table of Contents

• Background
• Install
• Usage
• Maintainers
• Contributing
• License

Background

I initially developed this program to illustrate how to write client code for the ActivityPub API as part of my book for O'Reilly Media, "ActivityPub: Programming for the Social Web".

Install

The easiest way to install is from PyPI.

pipx install activitypub-cli

Usage

ap uses the subcommand pattern common with other large command-line programs like git and docker. The full list of subcommands is available by typing ap --help. Familiarity with the ActivityPub protocol is helpful for understanding these commands!

ap login <id>

Logs in as a user to an ActivityPub API server using OAuth 2.0. The <id> argument is a Webfinger ID or the URL of the user's profile.

This stores the OAuth 2.0 token(s) in a file in the user's home directory, $HOME/.ap/token.json, so that subsequent commands can use them.

ap logout

Logs out of the current session by deleting the token file.

ap whoami

Shows the currently logged-in user.

ap get <id>

Gets the object with the given ID and prints it to stdout.

ap inbox

ap outbox

ap followers

ap following

ap pending followers

ap pending following

Shows these collections for the currently logged-in user.

ap follow <id>

Follows the user with the given ID.

ap accept follower <id>

ap reject follower <id>

Accepts or rejects a follow request from the user with the given ID.

ap undo follow <id>

Unfollows the user with the given ID.

ap create note <text>

Creates a Note object with the given text.

ap upload <filename>

Uploads the given file and prints the resulting URL.

Maintainers

• @evanp (Evan Prodromou; @[e-mail] on Mastodon)

Contributing

The project uses uv. To get set up, clone from Git and set up a virtual environment:

git clone https://github.com/evanp/ap.git
cd ap
uv venv
source .venv/bin/activate
uv pip install -e .

Then you can run the application directly:

ap -h

I'm very interested in contributions to this project. Some quick notes:

• Please open an issue before starting work on a new feature. This will help us coordinate and make sure that the feature is a good fit for the project.
• Ideally, commands should map closely to the ActivityPub protocol. If you're not sure how to do that, please open an issue and we can discuss it.
• Please make sure that your code passes the existing tests, and add new tests as appropriate.
• Please make your code format correctly with Python Black.

Small note: If editing the Readme, please conform to the standard-readme specification.

License

GPL v3 or later