enbas/README.asciidoc

= 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 currently a work in progress so breaking changes will be
made and bugs may appear here and there during its early development.
Enbas has limited functionality at the moment and it is **not** recommended for use
with your production GoToSocial servers.

This project is licensed under GPLv3.

=== 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 is that the binary's 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
cd enbas/internal/build/
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`.

==== 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

Use the `login` command to log into your GoToSocial account with Enbas.

[source,console]
----
enbas login --instance gotosocial.example.local
----

The login flow uses Oauth2 authentication and requires your interaction to complete the process. 
The process uses the following steps:

1. The application will register itself and the GTS server will create a new client ID and secret that it needs for authentication.

2. The application will then generate a link to the consent form for you to access in your browser.
If you're on Linux the link will open in a new browser.
If you're using a different OS or the browser tab doesn't open you can manually open the link in a new browser tab.

- Once you've signed in GTS will ask you to confirm that you want to create an out of band token for Enbas. Once you've clicked accept a token will be printed for you. Copy this token and return to your terminal.

- Paste the token into the prompt and press ENTER. Enbas will then exchange the token for and access token which will be used for authentication on your behalf. Enbas will then verify the access token and confirm that you have successfully logged into your account.


=== View your account information

=== View a remote account

=== View your timeline

=== View a status

== 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.]