path: root/extra/adenosine.1

.\" Generated by scdoc 1.11.2
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "adenosine" "1" "2023-08-21" "adenosine CLI Client Manual Page"
.P
.SH NAME
.P
adenosine - command-line client for AT protocol (atproto.\&com)
.P
.SH SYNOPSIS
.P
adenosine [OPTIONS] <COMMAND> <ARGS>
.P
.SH DESCRIPTION
.P
This is a simple, enthusiast-grade CLI client for the work-in-progress AT
Protocol (atproto.\&com).\& It is an entirely "delegated" client, which means that
it does not store or cache any user content locally; everything works by making
HTTP/XRPC requests to a Personal Data Server (PDS), which is usually a remote
service.\&
.P
The only real utility of this tool currently is messing around with prototype
implementations, possibly while developing them.\&
.P
This client does not currently do any schema validation of Lexicons, either at
compile time or runtime (eg, dynamically fetching Lexicons).\& The Bluesky
Lexicon (bsky.\&app) is partially supported with helper commands.\&
.P
.SH FIELD SYNTAX
.P
Several commands accept generic key/value fields which are passed through as
either query parameters or combined together in to a request body JSON object.\&
Escaping and other corner-cases aren'\&t handled.\&
.P
\fB==\fR
.RS 4
Query parameter.\& Key and Value both passed as strings.\&
.P
.RE
\fB=\fR
.RS 4
Body fields, combined together as a JSON object.\& Keys are strings, values are parsed as JSON with fall-through to string type.\&
.P
.RE
For example, the argument list \fBlimit==25 title="regarding documentation" year=2022 tags='\&["blue", "green"]'\&\fR
would be interpreted as a single query parameter "limit" with value "25", and a
JSON object with keys "title" (string value), "year" (number value), "tags"
(array of strings).\&
.P
.SH COMMANDS
.P
\fBstatus\fR
.RS 4
Summarizes configuration, and (TODO) connection and authentication to the API server.\& Useful for debugging.\&
.P
.RE
\fBdescribe\fR [name]
.RS 4
Prints repository description fetched from PDS
.P
.RE
\fBresolve\fR <name>
.RS 4
Has PDS resolve handle to a DID
.P
.RE
.SS Generic XRPC Requests
.P
It is possible to construct and submit a generic XRPC request to the PDS, and
prints any response.\&See field syntax section above about query parameters and
body fields.\& Body fields only used for "post" requests.\&
.P
\fBxrpc\fR <"get"|"post"> <nsid> [fields]+
.P
.SS Generic Record Interaction
.P
\fBls\fR <at-uri>
.RS 4
List either collections under a repository, or records under a collection
.P
.RE
\fBget\fR <at-uri>
.RS 4
Fetch and print a single record
.P
.RE
\fBcreate\fR <collection> [fields].\&.\&.\&
.RS 4
Construct and create a generic record, printing the resulting AT-URI and CID
.P
.RE
\fBupdate\fR <at-uri> [fields].\&.\&.\&
.RS 4
Fetch record, update fields, "put" back to same record path
.P
.RE
\fBdelete\fR <at-uri>
.RS 4
Delete a single record from repository
.P
.RE
.SS Bluesky (bsky.app)
.P
\fBbsky feed\fR
.RS 4
Fetch the home feed, or account feed for a specific user
.P
.RE
\fBbsky follow\fR
.RS 4
Create a '\&follow'\& record for the target by AT URI
.P
.RE
\fBbsky like\fR
.RS 4
Create a '\&like'\& record for the target by AT URI
.P
.RE
\fBbsky notifications\fR
.RS 4
Fetch notification feed
.P
.RE
\fBbsky post\fR
.RS 4
Create a new '\&post'\& record
.P
.RE
\fBbsky profile\fR
.RS 4
Display a profile record (or self if not provided)
.P
.RE
\fBbsky repost\fR
.RS 4
Create a '\&repost'\& record for the target by AT URI
.P
.RE
\fBbsky search-users\fR
.RS 4
Query by partial handle
.P
.P
.RE
.SS Account Management
.P
\fBaccount register --email <email> --password <password> --handle <handle>\fR
.P
\fBaccount login --password <password> --handle <handle>\fR
.RS 4
Create a new authenticated session
.P
.RE
\fBaccount logout\fR
.RS 4
Deletes the current login session
.P
.RE
.SS Raw Repository Management
.P
\fBrepo export [did]\fR
.RS 4
Dump raw binary repository as CAR format to stdout
.P
.RE
\fBrepo import [did]\fR
.RS 4
Read raw binary repository as CAR format from stdin, and import to PDS
.P
.RE
\fBrepo head [did]\fR
.RS 4
Get the latest commit for a DID
.P
.RE
.SH OPTIONS
.P
\fB-h, --help\fR
.RS 4
Prints help information
.P
.RE
\fB-V, --version\fR
.RS 4
Prints version information
.P
.RE
\fB-v, --verbose\fR
.RS 4
Pass many times for more log output
By default, it'\&ll only report errors.\& Passing `-v` one time also prints warnings, `-vv` enables info logging, `-vvv` debug, and `-vvvv` trace.\&
.P
.RE
\fB--pds-host <atp-host>\fR [env: ATP_PDS_HOST]
.P
\fB--auth-token <auth-token>\fR [env: ATP_AUTH_TOKEN]
.P
.SH GETTING STARTED
.P
To start interacting with a PDS, set the `ATP_PDS_HOST` environment variable.\& Then
either register a test account, or create a new session for an existing
account, and save the JWT token to the `ATP_AUTH_TOKEN`:
.P
.nf
.RS 4
# default port for bluesky-social/atproto implementation
export ATP_PDS_HOST=http://localhost:2583

# register a new account
adenosine account register -u voltaire\&.test -p bogus -e voltaire@example\&.com
{
	"did": "did:plc:yqtuksvatmmgngd5nkkw75hn",
	"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\&.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjMwNn0\&.MMQa4JIQdwvhy-rjJ0kO-z8-KdoOL0Lto9JtOkK-lwE",
	"handle": "voltaire\&.test"
}

export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\&.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjMwNn0\&.MMQa4JIQdwvhy-rjJ0kO-z8-KdoOL0Lto9JtOkK-lwE

# to clear the auth token env variable
unset ATP_AUTH_TOKEN

# create a new session (login) for existing account
adenosine account login -u voltaire\&.test -p bogus
{
	"did": "did:plc:yqtuksvatmmgngd5nkkw75hn",
	"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\&.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjQxNX0\&.j2wcF1g9NxT_1AvYRiplNf_jtK6S81y3L38AkcBwOqY",
	"name": "voltaire\&.test"
}

export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\&.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjQxNX0\&.j2wcF1g9NxT_1AvYRiplNf_jtK6S81y3L38AkcBwOqY
.fi
.RE
.P
You could save the `ATP_PDS_HOST` and `ATP_AUTH_TOKEN` values in `~/.\&bashrc` so you
don'\&t need to enter them every time.\&
.P
Now you can start posting and poking around:
.P
.nf
.RS 4
adenosine bsky post "gruel again for breakfast"
{
	"cid": "bafyreig2aqlsg4arslck64wbo2hnhe6k2a4z3z2sjfzh3uapv3a4zjld7e",
	"uri": "at://did:plc:yqtuksvatmmgngd5nkkw75hn/app\&.bsky\&.post/3jg5zkr322c2a"
}

adenosine ls at://voltaire\&.test
app\&.bsky\&.post
.fi
.RE