CLI: update manpage, CLI args, README

1 files changed, 209 insertions, 7 deletions

diff --git a/extra/adenosine.1 b/extra/adenosine.1
index 7a490d3..dcac2dd 100644
--- a/extra/adenosine.1
+++ b/extra/adenosine.1
@@ -5,7 +5,7 @@
 .nh
 .ad l
 .\" Begin generated content:
-.TH "adenosine" "1" "2022-10-27" "adenosine Client Tool Manual Page"
+.TH "adenosine" "1" "2022-10-28" "adenosine CLI Client Manual Page"
 .P
 .SH NAME
 .P
@@ -17,18 +17,170 @@ adenosine [OPTIONS] <COMMAND> <ARGS>
 .P
 .SH DESCRIPTION
 .P
-TODO
+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
-.SS Other Commands
+\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 username 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 username
+.P
+.P
+.RE
+.SS Account Management
+.P
+\fBaccount register --email <email> --password <password> --username <username>\fR
 .P
+\fBaccount info\fR
 .RS 4
-\fBstatus\fR [--json]
+Fetches account metadata for the current session
+.P
+.RE
+\fBaccount login --password <password> --username <username>\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
-Summarizes connection and authentication to the API server.\& Useful for debugging
+Read raw binary repository as CAR format from stdin, and import to PDS
 .P
 .RE
+\fBrepo root [did]\fR
+.RS 4
+Get the current 'root' commit for a DID
+.P
 .RE
 .SH OPTIONS
 .P
@@ -52,6 +204,56 @@ By default, it'll only report errors.\& Passing `-v` one time also prints warnin
 .P
 \fB--auth-token <auth-token>\fR [env: ATP_AUTH_TOKEN]
 .P
-.SH EXAMPLES
+.SH GETTING STARTED
 .P
-TODO
+To start interacting with a PDS, set the `ATP_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_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",
+	"username": "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_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