diff --git a/README.asciidoc b/README.asciidoc deleted file mode 100644 index 15f4427..0000000 --- a/README.asciidoc +++ /dev/null @@ -1,256 +0,0 @@ -// SPDX-FileCopyrightText: 2024 Dan Anglin -// -// SPDX-License-Identifier: CC-BY-4.0 - -= Enbas -:toc: left -:toclevels: 3 -:toc-title: Table of Contents - -== Overview - -Enbas is a https://docs.gotosocial.org/en/latest/[GoToSocial] client for your terminal written -in https://go.dev[Go]. The project is in its experimental stages of development so bugs and breaking -changes may appear. Enbas has limited functionality at the moment and it is **not** recommended for use -with your production GoToSocial servers. - -This project is licensed under the GNU General Public License V3 or later which you can view link:LICENSES/GPL-3.0-or-later.txt[here]. - -=== Repository mirrors - -- **Code Flow:** https://codeflow.dananglin.me.uk/apollo/enbas -- **Codeberg:** https://codeberg.org/dananglin/enbas -- **GitHub:** https://github.com/dananglin/enbas - -== Installation - -=== Download - -Pre-built binaries will be available on the release page on both Codeberg and GitHub when the first -release is made. - -=== Build from source - -==== Requirements - -===== Go - -A minimum version of Go 1.22.0 is required for installing spruce. -Please go https://go.dev/dl/[here] to download the latest version. - -===== Mage (Optional) - -The project includes mage targets for building and installing the binary. -The main advantage of using mage over `go install` is that the build information is baked into the binary -during compilation. You can visit the https://magefile.org/[Mage website] for instructions on how to install Mage. - -==== Install with mage - -You can install Enbas with Mage using the following commands: - -[source,console] ----- -git clone https://github.com/dananglin/enbas.git -mage install ----- - -By default Mage will attempt to install Enbas to `/usr/local/bin/enbas` which will most likely fail as you won't -the permission to write to `/usr/local/bin/`. You will need to either run `sudo mage install`, or you can -(preferably) change the install prefix to a directory that you have permission to write to using -the `ENBAS_INSTALL_PREFIX` environment variable. For example: - -[source,console] ----- -ENBAS_INSTALL_PREFIX=${HOME}/.local mage install ----- - -This will install Enbas to `~/.local/bin/enbas`. - -===== Environment variables you can use with Mage - -[%header,cols=2*] -|=== -|Environment Variable -|Description - -|`ENBAS_INSTALL_PREFIX` -|Set this to your preferred the installation prefix (default: `/usr/local`). - -|`ENBAS_BUILD_REBUILD_ALL` -|Set this to `1` to rebuild all packages even if they are already up-to-date. - -|`ENBAS_BUILD_VERBOSE` -|Set this to `1` to enable verbose logging when building the binary. -|=== - -==== Install with go - -If your `GOBIN` directory is included in your `PATH` then you can install Enbas with Go. - -[source,console] ----- -git clone https://github.com/dananglin/enbas.git -cd enbas -go install ./cmd/enbas ----- - -== Configuration - -Enbas uses Go's https://pkg.go.dev/os#UserConfigDir[os.UserConfigDir()] function to determine the -location of your configuration directory. - -If you've set the `XDG_CONFIG_HOME` environment variable, the configuration files will be stored in the `$XDG_CONFIG_HOME/enbas` directory. - -If this is not set: - -- on Linux the configuration directory will be set to `$HOME/.config/enbas`. -- on Darwin (MacOS) the configuration directory will be set to `$HOME/Library/Application Support/enbas`. -- on Windows the configuration directory will be set within the `%AppData%` directory. - -If, for whatever reason, any of the above cannot be determined the configuration directory will be set to -the current working directory. - -== Usage - -=== Check the build information - -You can view the application's version and build information using the `--version` flag. -The build information is correctly displayed if you've downloaded the binary from Codeberg or GitHub, -or if you've built it with Mage. - -[source,console] ----- -$ enbas version --full -Enbas - Version: v0.0.0-13-g26a909d - Git commit: 26a909d - Go version: go1.22.0 - Build date: 2024-02-25T15:22:55Z ----- - -=== Check out the help documentation - -You can view the help documentation with the `--help` flag. -You can also use this flag to view the help documentation for any of the commands. - -[source,console] ----- -$ enbas --help -SUMMARY: - enbas - A GoToSocial client for the terminal. - -VERSION: - v0.0.0-13-g26a909d - -USAGE: - enbas [flags] - enbas [command] - -COMMANDS: - login login to an account on GoToSocial - show print details about a specified resource - switch switch to an account - version print the application's version and build information - -FLAGS: - --help - print the help message - -Use "enbas [command] --help" for more information about a command. ----- - -=== Log into your GoToSocial account - -Enbas uses the Oauth2 authentication flow to log into your account on GoToSocial. -This process requires your input to give consent to allow Enbas access to your account. - -[WARNING] -==== -As of writing GoToSocial does not currently support scoped authorization tokens so even if we request read-only -tokens, the application will be able to perform any actions within the limitations of your account -(including admin actions if you are an admin). -You can read more about this https://docs.gotosocial.org/en/latest/api/authentication/[here]. -==== - -The login flow is completed using the following steps: - -1. You start by using the `login` command specifying the instance that you want to log into. -+ -[source,console] ----- -enbas login --instance gotosocial-01.social.example ----- - -2. The application will register itself and the GoToSocial server will create a new client ID and secret that the app needs for authentication. - -3. The application will then generate a link to the consent form for you to access in your browser. -This link will be printed on your terminal screen along with a message explaining that you need to obtain the `out-of-band` token to continue. -If you have the `BROWSER` environment variable set or if you're using Linux, the link will open in a new browser tab for you to sign into your account. -If the browser tab doesn't open, you can manually copy and paste the link in your favourite browser. - -4. Once you've signed into GoToSocial on your browser, you will be informed that Enbas would like to perform actions on your behalf. -If you're happy with this then click on the `Allow` button. -+ -image::assets/images/consent_form.png[A screenshot of the consent form] - -5. The `out-of-band` token will be printed for you at this point. Copy it and return to your terminal. - -6. Paste the token into the prompt and press `ENTER`. -Enbas will then exchange the token for an access token which will be used to authentication to the -GoToSocial server on your behalf. -Enbas will then verify the access token, save the credentials to the `credentials.json` file in your configuration directory, -and confirm that you have successfully logged into your account. -+ -[source,console] ----- -$ enbas login --instance gotosocial-01.social.example - -You'll need to sign into your GoToSocial's consent page in order to generate the out-of-band token to continue with -the application's login process. Your browser may have opened the link to the consent page already. If not, please -copy and paste the link below to your browser: - -https://gotosocial-01.social.example/oauth/authorize?client_id=01RHK48N1KH9SFNH2VVZR414BJ&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code - -Once you have the code please copy and paste it below. - -Out-of-band token: ZGJKNDA2YWMTNGEYMS0ZZJLJLWJHNDITM2IZYJJLNJM3YJBK -Successfully logged into bobby@gotosocial-01.social.example ----- - -=== Common actions - -* View your account information -+ -[source,console] ----- -enbas show --type account --my-account ----- - -* View a local or remote account -+ -[source,console] ----- -enbas show --type account --account teddy@gotosocial-01.social.example ----- - -* View your home timeline -+ -[source,console] ----- -enbas show --type timeline ----- - -* View the details of a status -+ -[source,console] ----- -enbas show --type status --status-id 01HQE43KT5YEDN4RGMT7BC63PF ----- - -== Inspirations - -This project was inspired from the following projects: - -* **madonctl:** https://github.com/McKael/madonctl[A Mastodon CLI client written in Go.] -* **toot:** https://pypi.org/project/toot/[A Mastodon CLI and TUI written in Python.] -* **tut:** https://github.com/RasmusLindroth/tut[A Mastodon TUI written in Go.] diff --git a/README.md b/README.md new file mode 100644 index 0000000..8369ae1 --- /dev/null +++ b/README.md @@ -0,0 +1,44 @@ + + +# Enbas + +### Overview + +Enbas is a [GoToSocial](https://docs.gotosocial.org/en/latest/) client for your terminal written +in [Go](https://go.dev). + +The project is in its early stages of development so expect bugs, breaking changes and limited +functionality. +At this time it is not recommended for use this with your production GoToSocial instances. + +### Repository mirrors + +Enbas is actively developed in [Code Flow](https://codeflow.dananglin.me.uk/apollo/enbas) with +the `main` branch mirrored to [Codeberg](https://codeberg.org/dananglin/enbas) and +[GitHub](https://github.com/dananglin/enbas). + +### Documentation + +- **[Installation guide](./docs/install.md)**: A guide for installing Enbas on your machine. +- **[Getting started guide](./docs/getting_started.md)**: A guide to help you get started on using Enbas. +- **[Configuration reference](./docs/configuration.md)**: The configuration reference documentation. +- **[User manual](./docs/manual.md)**: The user manual. + +### Licensing + +Each file is annotated with the licensing information, but in general: + +- All original source code is licensed under GPL-3.0-or-later. +- All documentation is licensed under CC-BY-4.0. + +### Inspirations + +This project was inspired by the following projects: + +* **[madonctl](https://github.com/McKael/madonctl)**: A Mastodon CLI client written in Go. +* **[tut](https://github.com/RasmusLindroth/tut)**: A Mastodon TUI written in Go. +* **[toot](https://pypi.org/project/toot/)**: A Mastodon CLI and TUI written in Python. diff --git a/assets/images/consent_form.png b/assets/images/consent_form.png index 1b0948c..f1e8a13 100644 --- a/assets/images/consent_form.png +++ b/assets/images/consent_form.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:77cec529dc6133cd3b4fd219a99820aba24e4ecf99e1f6db41ada2bebc1bc1c2 -size 54240 +oid sha256:02def288f4a81dfbe2afa3cd133f32328a659e668999d0f123564a3e7e432bcf +size 40151 diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..8b1a20e --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,7 @@ + + +# Changelog diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..69c8379 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,35 @@ + + +# Configuration reference + +## Config + +| Field | Type | Description | +|--------------------|-------------------------------|--------------------------------------------------| +| `credentialsFile` | string | The (absolute) path to your credentials file. | +| `cacheDirectory` | string | The (absolute) path to the root cache directory. | +| `lineWrapMaxWidth` | int | The character limit used for line wrapping. | +| `http` | [HTTPConfig](#httpconfig) | HTTP settings. | +| `integrations` | [Integrations](#integrations) | Specify your integrations with Enbas. | + + +## HTTPConfig + +| Field | Type | Description | +|----------------|------|---------------------------------------------------------------------| +| `timeout` | int | The timeout (in seconds) for normal HTTP requests to your instance. | +| `mediaTimeout` | int | The timeout (in seconds) for retrieving media from your instance. | + +## Integrations + +| Field | Type | Description | +|---------------|--------|--------------------------------------------------------------------------------------------------------| +| `browser` | string | The browser used for opening URLs (e.g. URL to a remote account). | +| `editor` | string | The text editor used for writing statuses (not yet implemented). | +| `pager` | string | The pager used for paging through long outputs (e.g. status timelines). Leave blank to disable paging. | +| `imageViewer` | string | The image viewer used for viewing images from media attachments. | +| `videoPlayer` | string | The video player used for viewing videos from media attachments. | diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..2ae9d60 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,159 @@ + + +# Getting Started + +## Summary + +In this guide we are going to log into an account on a private GoToSocial server. + +Follow along to log into your own account. + +## Your configuration directory + +Enbas uses Go's [os.UserConfigDir()](https://pkg.go.dev/os#UserConfigDir) function to calculate the location of your configuration directory. + +If you've set the `XDG_CONFIG_HOME` environment variable, the configuration directory will be set to `$XDG_CONFIG_HOME/enbas`. + +If this is not set, then: + +- on Linux the configuration directory will be set to `$HOME/.config/enbas`. +- on Darwin (MacOS) the configuration directory will be set to `$HOME/Library/Application Support/enbas`. +- on Windows the configuration directory will be set within the `%AppData%` directory. + +Alternatively you can use the `--config-dir` global flag to specify your configuration directory. + +## Generate your configuration file + +Run the `init` command to generate your configuration file. + +```bash +enbas init +``` + +Use the `--config-dir` flag if you want to generate it in a specific directory + +```bash +enbas --config-dir ./config init +``` + +You should now see a file called `config.json` in your configuration directory. +Feel free to edit the file to your preferences. +The [configuration reference page](./configuration.md) should help you with this. + +For this 'Getting Started' guide you may want to specify your preferred browser in the configuration to allow +Enbas to open the link to your instance's authorisation page. +If you prefer to open the link manually then you can leave it blank. + +## Log into your GoToSocial account + +Enbas uses the Oauth2 authentication flow to log into your account on GoToSocial. + +> [!WARNING] +> As of writing GoToSocial does not currently support scoped authorization tokens so even if we request read-only +> tokens, the application will be able to perform any actions within the limitations of your account +> (including admin actions if you are an admin). +> You can read more about this [here](https://docs.gotosocial.org/en/latest/api/authentication/). + +Follow the below steps to log into your account: + +1. Run the `login` command specifying the instance that you want to log into. + ```bash + enbas login --instance gts.enbas-demo.private + ``` + +2. Enbas will send a registration request to your instance and receive a new client ID and secret that it + needs for authentication. + +3. Enbas will then generate a link to the consent form for you to access in your browser and print it to + your terminal screen along with a message explaining that you need to obtain the `out-of-band` token + to continue. + + The link will open in a tab in your preferred browser if you've specified it in your configuration, + otherwise you can manually open it yourself. + + If the browser tab doesn't open for you as expected you can still manually open it yourself. + +4. Once you've signed into GoToSocial on your browser, + you will be informed that Enbas would like to perform actions on your behalf. + If you're happy with this then click on the `Allow` button. + ![A screenshot of the consent form](../assets/images/consent_form.png "Consent Form") + +5. The `out-of-band` token from your instance will be displayed to you in your browser. + Copy it and return to your terminal. + +6. Paste the token into the prompt and press `ENTER`. + Enbas will then exchange the token for an access token which will be used to authenticate + to your instance on your behalf. + +7. Enbas will then verify the access token, save the credentials to the `credentials.json` file + in your configuration directory, and inform you that you have successfully logged into your account. + +### Example login flow + +``` +$ enbas login --instance gts.enbas-demo.private + +You'll need to sign into your GoToSocial's consent page in order to generate the out-of-band token to continue with the application's login process. +Your browser may have opened the link to the consent page already. If not, please copy and paste the link below to your browser: + +https://gts.enbas-demo.private/oauth/authorize?client_id=019RD0WVA903F773T5F9D9EYHP&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code + +Once you have the code please copy and paste it below. +Out-of-band token: ZDRKOTE0NMUTZGVHZC0ZNJVJLWJINTMTMWE1M2UWYWFHOTQY +✔ You have successfully logged as percy@gts.enbas-demo.private. +``` + +## View your account information + +You can verify that you have successfully logged in by viewing your account information. + +```bash +enbas show --type account --my-account +``` + +### Example + +``` +$ enbas show --type account --my-account + +Percy Cade (@percy) + +ACCOUNT ID: +01629QXYN8X597CZDAH4BTY32R + +JOINED ON: +29 Jun 2024 + +STATS: +Followers: 0 +Following: 0 +Statuses: 0 + +BIOGRAPHY: +Hey there, the name's Percy. + +I've been a Platform Engineer in the Healthcare industry for 5 years and +counting. I love containerising anything and everything with Docker and +Kubernetes, and often find myself dabbling with Python, Go and Rust. + +In my free time I like to cook, blog about FOSS software news and make videos +documenting my travels across the UK. + + +METADATA: +Pronouns: he/him +Location: Hertfordshire, UK +My website: https://percycade.me.private +My blogs: https://blogs.percycade.me.private +My photos: https://photos.percycade.me.private +My videos: https://videos.percycade.me.private + +ACCOUNT URL: +https://gts.enbas-demo.private/@percy +``` + +Now that you have successfully logged into your account proceed to the [user manual](./manual.md). diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..5b8ea3d --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,123 @@ + + +# Installation Guide + +## Download + +Pre-built binaries will soon be available on the release page on both Codeberg and GitHub. + +## Build from source + +### Build requirements + +- **Go:** A minimum version of Go 1.22.0 is required for installing spruce. + Please go [here](https://go.dev/dl/) to download the latest version. + +- **Mage (Optional):** The project includes mage targets for building and installing the binary. The main + advantage of using mage over `go install` is that the build information is baked into the binary during + compilation. You can visit the [Mage website](https://magefile.org/) for instructions on how to install Mage. + +### Install with mage + +You can install Enbas with Mage using the following commands: + +```bash +git clone https://github.com/dananglin/enbas.git +mage install +``` + +By default Mage will attempt to install Enbas to `/usr/local/bin/enbas` which will most likely fail as you won't +the permission to write to `/usr/local/bin/`. You will need to either run `sudo mage install`, or you can +(preferably) change the install prefix to a directory that you have permission to write to using +the `ENBAS_INSTALL_PREFIX` environment variable. For example: + +```bash +ENBAS_INSTALL_PREFIX=${HOME}/.local mage install +``` + +This will install Enbas to `~/.local/bin/enbas`. + +The table below shows all the environment variables you can use when building with Mage. + +| Environment Variable | Description | +|--------------------------|------------------------------------------------------------------------------| +|`ENBAS_INSTALL_PREFIX` | Set this to your preferred the installation prefix (default: `/usr/local`). | +|`ENBAS_BUILD_REBUILD_ALL` | Set this to `1` to rebuild all packages even if they are already up-to-date. | +|`ENBAS_BUILD_VERBOSE` | Set this to `1` to enable verbose logging when building the binary. | + +### Install with go + +If your `GOBIN` directory is included in your `PATH` then you can install Enbas with Go. + +```bash +git clone https://github.com/dananglin/enbas.git +cd enbas +go install ./cmd/enbas +``` + +## Verify the installation + +Type `enbas` from your terminal to verify that the installation was successful. You should see the help documentation. + +```bash +$ enbas +SUMMARY: + enbas - A GoToSocial client for the terminal. + +VERSION: + v0.1.0 + +USAGE: + enbas [flags] + enbas [flags] [command] + +COMMANDS: + accept Accept a request (e.g. a follow request) + add Add a resource to another resource + block Block a resource (e.g. an account) + create Create a specific resource + delete Delete a specific resource + edit Edit a specific resource + follow Follow a resource (e.g. an account) + init Create a new configuration file in the specified configuration directory + login Login to an account on GoToSocial + mute Mute a resource (e.g. an account) + reject Reject a request (e.g. a follow request) + remove Remove a resource from another resource + show Print details about a specified resource + switch Perform a switch operation (e.g. switch logged in accounts) + unblock Unblock a resource (e.g. an account) + unfollow Unfollow a resource (e.g. an account) + unmute Unmute a resource (e.g. an account) + version Print the application's version and build information + whoami Print the account that you are currently logged in to + +FLAGS: + --help + print the help message + --config-dir + Specify your config directory + --no-color + Disable ANSI colour output when displaying text on screen + +Use "enbas [command] --help" for more information about a command. +``` + +You can also view the application's version and build information using the `version` command. +The build information is correctly displayed if you've downloaded the binary from Codeberg or GitHub, +or if you've built it with Mage. + +```bash +Enbas + +Version: v0.1.0 +Git commit: c8892a6 +Go version: go1.22.4 +Build date: 2024-06-28T21:57:37Z +``` + +Once you have completed the installation proceed to the [Getting Started guide](./getting_started.md). diff --git a/docs/manual.md b/docs/manual.md new file mode 100644 index 0000000..28df53f --- /dev/null +++ b/docs/manual.md @@ -0,0 +1,9 @@ + + +# User Manual + +_Coming soon_ diff --git a/internal/executor/login.go b/internal/executor/login.go index c84f3ea..e13a1b2 100644 --- a/internal/executor/login.go +++ b/internal/executor/login.go @@ -100,7 +100,7 @@ func (l *LoginExecutor) Execute() error { return fmt.Errorf("unable to save the authentication details: %w", err) } - l.printer.PrintSuccess("Successfully logged into " + loginName + ".") + l.printer.PrintSuccess("You have successfully logged as " + loginName + ".") return nil }