A command line tool to invoke AT Protocol XRPC methods.
Manages authentication sessions locally, automatically refreshing expired tokens as needed. Supports queries, procedures, and raw byte uploads.
brew tap ngerakines/tap
brew install atpxrpc% atpxrpc login ngerakines.me abcd-efgh-ijkl-mnop
Resolving ngerakines.me...
Resolved to did:plc:cbkjy5n7bk3ax2wplmtjofq2 (https://pds.cauda.cloud)
Creating session...
Logged in as ngerakines.me (did:plc:cbkjy5n7bk3ax2wplmtjofq2)
% atpxrpc --handle ngerakines.me com.atproto.server.getServiceAuth aud=did:web:com.example.foo lxm=com.example.foo
{
"token": "eyJ0eXAiOiJKV1QiLC..."
}
% GADGET=$(cat gadget.jpg | atpxrpc --handle ngerakines.me --bytes --content-type image/png com.atproto.repo.uploadBlob)
% echo $GADGET
{
"blob": {
"$type": "blob",
"ref": {
"$link": "bafkreihydmbqvcnijilwwjim52ecfvkuhiy5kmwpbnh5ifskfihb7yv5ni"
},
"mimeType": "image/jpeg",
"size": 512713
}
}
% jo repo=did:plc:cbkjy5n7bk3ax2wplmtjofq2 collection=dev.ngerakines.cat \
record=$(jo '$type'=dev.ngerakines.cat text="Gadget" cat=$GADGET) \
| atpxrpc --handle ngerakines.me com.atproto.repo.createRecord
{
"uri": "at://did:plc:cbkjy5n7bk3ax2wplmtjofq2/dev.ngerakines.cat/3mgmxzafixf2i",
"cid": "bafyreiag5dh37ryx3tpbd5b2ydotvbtad4zuqjeytipozxlp4u3xobkpxe",
"commit": {
"cid": "bafyreiehhgwohshglchcjmd43udx4fsywn7zmuwinhvtekzpqh2uao5emi",
"rev": "3mgmxzagi7f2i"
},
"validationStatus": "unknown"
}$ atpxrpc --help
A command-line tool for making XRPC calls to AT Protocol services.
Manages authentication sessions in a local config file, automatically
refreshing expired tokens as needed.
SUBCOMMANDS:
login Log in with a handle and app password
logout Remove a stored account
accounts List all stored accounts
XRPC CALLS (default when no subcommand matches):
atpxrpc [--handle <handle>] <nsid> [key=value ...]
Query (GET): Pass key=value pairs as positional arguments.
Procedure (POST): Pipe JSON to stdin.
Bytes (POST): Use --bytes to send raw bytes from stdin.
EXAMPLES:
atpxrpc login alice.bsky.social xxxx-xxxx-xxxx-xxxx
atpxrpc com.atproto.repo.describeRepo repo=alice.bsky.social
atpxrpc com.atproto.repo.getRecord repo=did:plc:... collection=app.bsky.feed.post rkey=abc
jo repo=did:plc:... collection=app.bsky.feed.post record[text]=Hello | atpxrpc com.atproto.repo.createRecord
atpxrpc --handle bob.bsky.social com.atproto.repo.listRecords repo=did:plc:...
cat image.png | atpxrpc --bytes --content-type image/png com.atproto.repo.uploadBlob
ENVIRONMENT VARIABLES:
ATPXRPC_CONFIG Override config file path
PLC_HOSTNAME PLC directory hostname (default: plc.directory)
USER_AGENT HTTP user agent string
CERTIFICATE_BUNDLES Additional CA certificate bundles
DNS_NAMESERVERS Custom DNS nameserver addresses
Usage: atpxrpc [OPTIONS] [NSID] [PARAMS]...
atpxrpc <COMMAND>
Commands:
login Log in with a handle and app password, storing the session
logout Remove a stored account from the config
accounts List all stored accounts
check-auth Refresh the access token for an account if expired
proxy Send a proxied XRPC request through the PDS using the
atproto-proxy header
help Print this message or the help of the given subcommand(s)
Arguments:
[NSID]
XRPC method NSID (e.g., com.atproto.repo.getRecord)
[PARAMS]...
Query parameters as key=value pairs
Options:
--handle <HANDLE>
Handle of the account to use for the request
--out <OUT>
Write response body to a file instead of stdout
--bytes
Send raw bytes from stdin instead of JSON (forces POST)
--content-type <CONTENT_TYPE>
Content-Type header for --bytes mode
[default: application/octet-stream]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version