Overview

A screenshot enbas running inside tmux

enbas is a CLI application that allows you to interact with your GoToSocial instance from your terminal. With enbas you can perform operations such as:

reviewing your account information
viewing, creating, deleting and boosting statuses
viewing timelines
viewing media attachments from statuses using your favourite media player
viewing, following, and blocking accounts
creating and voting in polls
viewing, creating, editing and deleting your lists
…and much more

Motivation

This project was created from the desire to interact with my GoToSocial instance and explore the Fediverse from the comfort of my own terminal emulator. This application is developed for those who use GoToSocial and spend most of their time in the terminal. If you like the idea of scrolling through your timelines in your favourite terminal emulator instead of a GUI or a browser then enbas might interest you.

Requirements

Your favourite terminal emulator: For best results choose a modern terminal emulator such as Alacritty, Kitty, Foot, Ghostty or Wezterm. By default enbas uses ANSI colours so make sure your terminal is configured to use your favourite colour scheme.
A nerd font: A nerd font is required to correctly display icons such as displaying the boost icon when viewing a status. Make sure you have a nerd font installed and that your favourite terminal emulator is configured to use it. See https://www.nerdfonts.com/ for more information about nerd fonts.
A browser: A browser is needed for you to complete the login process and if you want to view certain resources in the browser such as an account or a status.
A video player (optional): A video player is required if you want to play videos from media attachments.
An image viewer (optional): An image viewer is required if you want to view images from media attachments.
An audio player (optional): An audio player is required if you want to play audio from media attachments.

Development

This project is actively developed in Code Flow with the main branch mirrored to Codeberg.

Licensing

The licensing information associated with each file is specified in the REUSE.toml file, but in general:

All original source code is licensed under GPL-3.0-or-later.
All documentation is licensed under CC-BY-4.0.

Inspiration

This project was inspired by the following projects:

madonctl: A Mastodon CLI client written in Go.
tut: A Mastodon TUI written in Go.
toot: A Mastodon CLI and TUI written in Python.

Installation guide

This project does not produce pre-built binaries in order to give you complete control when building and installing the application. The installation process is pretty simple and the guide below provides step-by-step instructions to help you out.

Build requirements

go: A minimum version of Go 1.25.4 is required for building enbas. Visit https://go.dev/dl/ to download the latest version.
mage: Mage is a build tool similar to make. The project includes mage targets for building the binary, the man pages and the example configuration file. Visit https://magefile.org/ for instructions on how to install mage.
git (optional): Git is used to calculate the binary version and commit reference. This is optional as these values can be set manually via environment variables.

Obtain the source code

You can obtain the source code by cloning the repository or downloading the source code.

Clone the repository

You can clone the repository from Codeberg or Code Flow.

from Codeberg

git clone https://codeberg.org/dananglin/enbas.git
cd enbas

or from Code Flow

git clone https://codeflow.dananglin.me.uk/apollo/enbas.git
cd enbas

Download the source code

You can download the source code from Codeberg or Code Flow.

from Codeberg

curl -sL https://codeberg.org/dananglin/enbas/archive/main.tar.gz -o enbas-main.tar.gz
tar xzvf enbas-main.tar.gz
cd enbas

or from Code Flow

curl -sL https://codeflow.dananglin.me.uk/apollo/enbas/archive/main.tar.gz -o enbas-main.tar.gz
tar xzvf enbas-main.tar.gz
cd enbas

Build

Build the binary and the manual using the following commands.

mage build
mage docs:manual

If you’ve obtained the source code by downloading the TAR archive and you want enbas to display the correct build information, you’ll need to set the environment variables to specify the version and commit reference.

# example
export ENBAS_APP_VERSION="v0.3.0"
export ENBAS_APP_COMMIT_REF="8abfe5e9d32fe1a07c4d6907b64ca3eb34489bec"
mage build
mage docs:manual

Once the build is successfully you should see the __build directory containing the binary, the man pages and the example configuration file.

$ tree __build/
__build/
├── bin
│   └── enbas
└── share
    ├── doc
    │   └── enbas
    │       └── examples
    │           └── config.json
    └── man
        ├── man1
        │   └── enbas.1
        ├── man5
        │   └── enbas.5
        └── man7
            └── enbas-topics.7

10 directories, 5 files

Install

You can install enbas system-wide or locally in your home directory.

System-wide installation

The below set of commands assumes that you want to install the binary within the /usr/local directory. Don’t forget to use sudo if installing to /usr/local requires escalated privileges.

# install the binary
install --mode 0755 __build/bin/enbas /usr/local/bin

# install the man pages
install -D --mode 0644 __build/share/man/man1/enbas.1 /usr/local/share/man/man1/enbas.1
install -D --mode 0644 __build/share/man/man5/enbas.5 /usr/local/share/man/man5/enbas.5
install -D --mode 0644 __build/share/man/man7/enbas-topics.7 /usr/local/share/man/man7/enbas-topics.7

# install the example configuration file
install -D --mode 0644 __build/share/doc/enbas/examples/config.json /usr/local/share/doc/enbas/examples/config.json

Local installation

The below set of commands assumes that you want to install the binary within the ${HOME}/.local directory.

# install the binary
install --mode 0700 __build/bin/enbas ${HOME}/.local/bin

# install the man pages
install -D --mode 0600 __build/share/man/man1/enbas.1 ${HOME}/.local/share/man/man1/enbas.1
install -D --mode 0600 __build/share/man/man5/enbas.5 ${HOME}/.local/share/man/man5/enbas.5
install -D --mode 0600 __build/share/man/man7/enbas-topics.7 ${HOME}/share/man/man7/enbas-topics.7

# install the example configuration file
install -D --mode 0600 __build/share/doc/enbas/examples/config.json ${HOME}/.local/share/doc/enbas/examples/config.json

Verify

Run enbas from your terminal to verify that the installation was successful. You should see the usage documentation.

You can also view the application’s build information by running enbas version.

Getting started

In this guide we are going to log into an account on a private GoToSocial server.

Follow along to log into your own account.

Create and edit your configuration file

The configuration for enbas is stored in a JSON formatted file. The default path to the configuration file is set to $XDG_CONFIG_HOME/enbas/config.json.

If the XDG_CONFIG_HOME environment variable is not set then:

on Linux the path will be set to $HOME/.config/enbas/config.json.
on Darwin (MacOS) the path will be set to $HOME/Library/Application Support/enbas/config.json.
on Windows the path will be set within the %AppData% directory.

Alternatively you can use the --config top-level flag to specify a custom path to your configuration file.

Run the following command to generate your configuration file.

# Create a new configuration using the default path.
enbas create config

# Or create a new configuration using a custom path.
enbas --config /path/to/your/new/config.json create config

You can use the example configuration to help you edit your own. You may recall that when installing the application you may have also generated and installed the example configuration system-wide (at /usr/local/share/doc/enbas/examples/config.json) or locally within your home directory (at ${HOME}/.local/share/doc/enbas/examples/config.json). You can also find a copy on Code Flow or on Codeberg.

For more details about the configuration options see the Configuration reference page.

For this ‘Getting Started’ guide you may want to specify your favourite browser in the configuration so that enbas can open the link to your instance’s authorisation page during the login flow. If you prefer to open the link manually then you can leave this field empty.

Log into your GoToSocial account

enbas uses GoToSocial’s Oauth2 authentication flow to log into your Fediverse account. Follow the below steps to complete the login process.

Run the following command to begin the login process. Use the --url to specify the URL of the instance that you want to log into. Use the --scope flag to specify the scope of your access (e.g. read, write). You can use the --scope flag multiple times to specify multiple scopes.
```
enbas login --url gts.mydomain.example --scope read --scope write
```
enbas will send a registration request to your instance and receive a new client ID and secret that it needs for authentication.
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. Alternatively you can manually open it yourself.

If the browser tab doesn’t open for you as expected you can still open the link manually.
Once you’ve signed into GoToSocial in your browser, you will be informed that enbas would like to perform actions on your behalf with the scopes that you’ve specified earlier. If you’re happy with this then click on the big Allow button.
The out-of-band token from your instance will be displayed to you in your browser. Copy it and return to your terminal.
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.
Finally, enbas will then verify the access token, save the credentials to the credentials file at the path specified in your configuration file, and inform you that you have successfully logged into your account.

$ enbas login --url super-cell.gts.enbas.private --scope read --scope write

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://super-cell.gts.enbas.private/oauth/authorize?client_id=01C5TAJ1GC1HFH45BV3BNRSZ1M&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&scope=read+write

Once you have the code, please copy and paste it below.
Out-of-band token: NJVMZGMWZMUTNJDKZI0ZZJNLLWI3NDATYTNJYWE0MJBLOGI5
✔ You have successfully logged in as victor@super-cell.gts.enbas.private.

View your account information

You can verify that you have successfully logged in by viewing your account information by running enbas show account --my-account.

$ enbas show account --my-account

Victor (@victor)

ACCOUNT ID:
01XWASN1G5K23ZBYCZHR4KQS3C

JOINED ON:
24 Apr 2025

STATS:
Followers: 0
Following: 0
Statuses: 0

BIOGRAPHY:
Hey there, the name's Victor.

I've been a Platform Engineer in the Healthcare industry for 7 years and
counting. I love containerising anything and everything with #docker and #k8s,
and often find myself dabbling with #python, #golang 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
Website: https://victor.me.private
Blogs: https://blogs.victor.me.private
Photos: https://photos.victor.me.private
Streams: https://streams.victor.me.private

ACCOUNT URL:
https://super-cell.gts.enbas.private/@victor

YOUR PREFERENCES:
Default post language: en
Default post visibility: public
Mark posts as sensitive by default: false

Configuration reference

Example configuration: See here at Codeberg or Code Flow

Config

Field	Type	Description
aliases	map[string]string	A set of shortnames mapped to the enbas command. This section is managed by enbas.
credentialsFile	string	The absolute path to your credentials file.
cacheDirectory	string	The absolute path to the root cache directory.
lineWrapMaxWidth	number (integer)	The maximum number of characters on a line before that line breaks. This setting is used when displaying a timeline, your notifications, your bookmarks, the list of statuses from an account, etc.
gtsClient	GTSClient	The settings for the GTS Client.
server	Server	The settings for running enbas in server mode.
integrations	Integrations	Integration settings.

GTSClient

Field	Type	Description
timeout	number (integer)	The timeout (in seconds) for API requests made to your GoToSocial instance.
mediaTimeout	number (integer)	The timeout (in seconds) for requests made for retrieving media from your GoToSocial instance.

Server

Field	Type	Description
socketPath	string	The path to the socket file that the backend server binds to. This file is used for the communication between the enbas client and the enbas server.
pidPath	string	The path to the backend server’s PID file. When the server starts it writes its process ID to this file. The enbas client reads from this file when it is called to stop the backend server.
idleTimeout	number (integer)	The time (in seconds) that the backend server can remain idle before shutting down. This setting is only used when running the server without the `--without-idle-timeout` flag.
logger	ServerLogger	The settings for the server’s logger.

ServerLogger

Field	Type	Description
level	string	The server’s general logging level. The accepted values are `debug`, `info`, `warn` and `error`. By default the logging level is set to `info`.
path	string	The path to the file where the logger will write the logs to. If this field is empty, the logger will write to the console.

Integrations

Field	Type	Description
browser	string	The command to run for opening the browser for viewing URLs (e.g. the URL of a remote account).
editor	string	The command to run for opening your favourite text editor for creating or editing statuses. (THIS INTEGRATION IS NOT YET USED).
pager	string	The command to run for piping long outputs into your favourite pager. To disable paging, leave this field blank.
imageViewer	string	The command to run for opening your favourite image viewer for viewing image files from media attachments.
videoPlayer	string	The command to run for opening your favourite video player for playing video files from media attachments.
audioPlayer	string	The command to run for opening your favourite audio player for playing audio files from media attachments.

Available operations

In this section of the documentation you can view all the commands that you can use with enbas. In this section, and as you interact more with enbas, you’ll come across the terms target, action and operation.

Target

A target is a resource that you can perform an action on. The target can be a GoToSocial resource (e.g. an account, a status or a timeline), or a local resource (e.g. your enbas configuration, your aliases or the usage documentation).

Action

An action is a built-in verb that describes the action to perform on a target. For example, the command enbas show status --status-id 01AV6D5YIKKEWDTLXTGVTTRW9dCHOLGJ uses the action keyword show to fetch and display the details of the status with the ID 01AV6D5YIKKEWDTLXTGVTTRW9dCHOLGJ.

Operation

An operation is the action that is performed on a particular target (e.g. create status), or the action performed on a target in relation to another target (e.g. add accounts to list).

You can view the targets that you can interact with under Available operations in the navigation menu. View the page of a specific target (e.g. status) for details on the operations you can perform on that target.

Top Level Flags

The top level flags below are available to all operations.

`--config`

The path to your configuration file.

Default: <empty>

`--no-color`

Disable the ANSI colour output when displaying the text on screen.

Default: false

access

The access target interacts with your access to your GoToSocial instance. Below are the operations you can perform on the access target.

create access

This operation creates a new access to your GoToSocial instance. This is the operation you’ll use to log into your GoToSocial instance. Enbas will use the Oauth2 authentication flow for the login process which is described in the ‘Getting started’ guide. You can run this command multiple times to log into multiple accounts.

Keyboard shortcuts

Project Enbas