apollo/enbas
1
0
Fork 0
Code Issues 4 Pull requests Projects Activity Actions

docs: updated documentation

Browse source 
- Converted documentation from Asciidoc to Markdown
- Updated the installation instructions and moved to a separate
  file in the docs directory.
- Updated the login instructions and moved to the Getting Started guide
  in the docs directory.
- Updated the licensing information in the main README.
- Created a page for changelog.
- Create a page for the user manual.
This commit is contained in:
Dan Anglin 2024-07-01 13:49:11 +01:00
parent b03b3c31cc
commit 23ec6048b5
Signed by: dananglin
GPG key ID: 0C1D44CFBEE68638
9 changed files with 380 additions and 259 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

256
README.asciidoc
View file

@ -1,256 +0,0 @@
// SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
//
// 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.]

44
README.md Normal file
View file

@ -0,0 +1,44 @@
<!--
SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
SPDX-License-Identifier: CC-BY-4.0
-->
# 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.

BIN
assets/images/consent_form.png (Stored with Git LFS)
View file

Binary file not shown.

7
docs/changelog.md Normal file
View file

@ -0,0 +1,7 @@
<!--
SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
SPDX-License-Identifier: CC-BY-4.0
-->
# Changelog

35
docs/configuration.md Normal file
View file

@ -0,0 +1,35 @@
<!--
SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
SPDX-License-Identifier: CC-BY-4.0
-->
# 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. |

159
docs/getting_started.md Normal file
View file

@ -0,0 +1,159 @@
<!--
SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
SPDX-License-Identifier: CC-BY-4.0
-->
# 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).

123
docs/installation.md Normal file
View file

@ -0,0 +1,123 @@
<!--
SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
SPDX-License-Identifier: CC-BY-4.0
-->
# 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).

9
docs/manual.md Normal file
View file

@ -0,0 +1,9 @@
<!--
SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
SPDX-License-Identifier: CC-BY-4.0
-->
# User Manual
_Coming soon_

2
internal/executor/login.go
View file

@ -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
}