From 37169128a020198cc6fd82b946fe0262c335014c Mon Sep 17 00:00:00 2001 From: Mike Lynch Date: Sat, 14 Dec 2024 17:40:49 +1100 Subject: [PATCH] Wrote some documentation for the register.py script --- README.md | 41 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 69e50e2..70b5ec1 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,40 @@ -## GoToSocial +# gotosocial -Putting together some client code for working with GoToSocial in Python \ No newline at end of file +A library for building GoToSocial bots + +## client + +This is a variant on my Mastodon bot code and hasn't been properly tested yet: I'll document it when I've done that. + +## register + +A utility for making it easier to register an app and get an access token for +a GoToSocial account - it's a Python script which automates as much of [the client API instructions](https://docs.gotosocial.org/en/latest/api/authentication/) as possible. There's still some manual stuff required for authenticating. + +This project is maintained with [uv](https://docs.astral.sh/uv/): install it, check out this repo and then you can run the script with the uv commands below and it should take care of dependencies. + +To register an app, you first need to give it an identity on the server - in the examples I've called the server `https://your.server/` and the app `mybot` + + uv run register -u https://your.server/ -n mybot + +This will create an app on the server and write out the client id and secret to a file in the current directory called `mybot_app.json`. It will also write a URL to the command line for the next step + +The second step is to visit that URL in an incognito browser window. You'll be prompted to authenticate - use the email address and password for the GoToSocial account which you want to post to via the app. + +Once you authenticate, you should be taken to a page which has a message like: + + Hi account! + + Here's your out-of-band token with scope "write", use it wisely: + + ABIGLONGSTRINGOFLETTERSANDNUMBERS + +Copy the out-of-band token and do the third step straight away, as the token will expire. + +The third step exchanges the above token for a permanent access token, by running the script again in the same directory, passing the OOB token with the -t flag: + + uv run register -u https://your.server/ -n mybot -t ABIGLONGSTRINGOFLETTERSANDNUMBERS + +If this is successful, your access token - another, different string of letters and numbers - will be printed to the command prompt. The access token is also written out as a json file with the name `mybot_at.json`. + +You should now be able to use the access token to post to your GoToSocial account.