enbas/docs/manual.md

<!--
SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>

SPDX-License-Identifier: CC-BY-4.0
-->

# User Manual

## Table of Contents

- [Global flags](#global-flags)
- [Version](#version)
  - [Print the application version](#print-the-application-version)
- [Init](#init)
- [Authentication](#authentication)
  - [Logging into an account](#logging-into-an-account)
  - [Switch between accounts](#switch-between-accounts)
  - [See the account that you are currently logged in as](#see-the-account-that-you-are-currently-logged-in-as)
- [Accounts](#accounts)
  - [View your own account](#view-your-own-account)
  - [View an account](#view-an-account)
  - [Follow an account](#follow-an-account)
  - [Unfollow an account](#unfollow-an-account)
  - [Show followers of an account](#show-followers-of-an-account)
  - [Show who an account is following](#show-who-an-account-is-following)
  - [Block an account](#block-an-account)
  - [Unblock an account](#unblock-an-account)
  - [View blocked accounts](#view-blocked-accounts)
  - [Mute an account](#mute-an-account)
  - [Unmute an account](#unmute-an-account)
  - [View muted accounts](#view-muted-accounts)
- [Follow requests](#follow-requests)
  - [View your follow requests](#view-your-follow-requests)
  - [Accept a follow request](#accept-a-follow-request)
  - [Reject a follow request](#reject-a-follow-request)
- [Statuses](#statuses)
  - [View a status](#view-a-status)
  - [Create a status](#create-a-status)
  - [Delete a status](#delete-a-status)
  - [Boost (Repost) a status](#boost-repost-a-status)
  - [Un-boost (Un-repost) a status](#un-boost-un-repost-a-status)
  - [Like a status](#like-a-status)
  - [Unlike a status](#unlike-a-status)
  - [Mute a status](#mute-a-status)
  - [Unmute a status](#unmute-a-status)
- [Polls](#polls)
  - [Create a poll](#create-a-poll)
  - [View a poll](#view-a-poll)
  - [Vote in a poll](#vote-in-a-poll)
- [Lists](#lists)
  - [Create a list](#create-a-list)
  - [View a list of your lists](#view-a-list-of-your-lists)
  - [View a specific list](#view-a-specific-list)
  - [Edit a list](#edit-a-list)
  - [Delete a list](#delete-a-list)
  - [Add accounts to a list](#add-accounts-to-a-list)
  - [Remove accounts from a list](#remove-accounts-from-a-list)
- [Timelines](#timelines)
  - [View a timeline](#view-a-timeline)
- [Media](#media)
  - [View media from a status](#view-media-from-a-status)
- [Bookmarks](#bookmarks)
  - [View your bookmarks](#view-your-bookmarks)
  - [Add a status to your bookmarks](#add-a-status-to-your-bookmarks)
  - [Remove a status from your bookmarks](#remove-a-status-from-your-bookmarks)
- [Notifications](#notifications)

## Global flags

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `config-dir` | string | false | The configuration directory. | |
| `no-color` | boolean | false | Disables ANSI colour output when displaying text on screen<br>You can also set `NO_COLOR` to any value for the same effect. | false |

## Version

### Print the application version

View the application's version and build information

```
enbas version --full
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `full` | boolean | false | Prints the full build information. | false |

## Init

Initialises the app by creating a configuration file in the configuration directory.
If you want to use a specific directory then use the global `--config-dir` flag.

```
enbas init
```

## Authentication

### Logging into an account

Log into your GoToSocial account. You can run this multiple times to log into multiple accounts.

```
enbas login --instance gts.enbas-demo.private
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `instance` | string | true | The instance that you want to log into. | |

### Switch between accounts

Switch between your logged in accounts.

```
enbas switch --to account --account-name vincent@gts.enbas-demo.private
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `to` | string | true | The resource you want to switch to. In this case you want `account`. | |
| `account-name` | string | true | The name of the account you want to switch to. | |

### See the account that you are currently logged in as

```
enbas whoami
```

## Accounts

### View your own account

Print the information of your own account.

```
enbas show --type account --my-account
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view. Here this should be `account`. | |
| `my-account` | boolean | true | Use this flag to view your own account. | |
| `show-preferences` | boolean | false | Show your posting preferences. | false |

### View an account

Prints the information of a local or a remote account.
If the account is unknown by your instance a `404` message will be shown instead.

```
enbas show --type account --account-name @name@example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view. Here this should be `account`. | |
| `account-name` | string | true | The name of the account to view. | |
| `skip-relationship` | boolean | false | Set to `true` to skip viewing your relationship to the account you are viewing (including the private note if you've created one). | false |

### Follow an account

Send a follow request to the account you want to follow.

```
enbas follow --type account --account-name @name@example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to follow. Here this should be `account`. | |
| `account-name` | string | true | The name of the account to follow. | |
| `show-reposts` | boolean | false | Show reposts from the account you want to follow. | true |
| `notify` | boolean | false | Get notifications when the account you want to follow posts a status. | false |

### Unfollow an account

Unfollow the account that you are currently following.
If you have a follow request pending for the account in question,
performing an unfollow action will remove said follow request.

```
enbas unfollow --type account --account-name @name@example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to unfollow. Here this should be `account`. | |
| `account-name` | string | true | The name of the account to unfollow. | |

### Show an account's followers

_TODO: provide instructions after updated implementation_

### Show account's followings

_TODO: provide instructions after updated implementation_

### Block an account

```
enbas block --type account --account-name @name@example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to block. Here this should be `account`. | |
| `account-name` | string | true | The name of the account to block. | |

### Unblock an account

```
enbas unblock --type account --account-name @name@example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to unblock. Here this should be `account`. | |
| `account-name` | string | true | The name of the account to unblock. | |

### View blocked accounts

Prints a list of accounts that you are currently blocking.

```
enbas show --type blocked
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `blocked` for blocked accounts. | |
| `limit` | integer | false | The maximum number of accounts to list. | 20 |

### Mute an account

```
enbas mute --type account --account-name @name@example.social --mute-notifications --mute-duration="1h"
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to mute.<br>Here this should be `account`. | |
| `account-name` | string | true | The name of the account to mute. | |
| `mute-notifications` | boolean | false | Set to `true` to mute notifications as well as statuses. | false |
| `mute-duration` | string | false | Specify how long the account should be muted for.<br>Set to `0s` to mute indefinitely | 0s (indefinitely). |

### Unmute an account

```
enbas unmute --type account --account-name @name@example.social 
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to unmute.<br>Here this should be `account`. | |
| `account-name` | string | true | The name of the account to unmute. | |

### View muted accounts

Prints a list of accounts that you have muted.

``` 
enbas show --type muted-accounts
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `muted-accounts`. | |
| `limit` | integer | false | The maximum number of accounts to print. | 20 |

### Add a private note to an account

Adds a private note to an account. Private notes can only be viewed by you.

```
enbas add --type note --to account --account-name @name@example.social --content "This person is awesome."
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to add.<br>Here this should be `note`. | |
| `to` | string | true | The resource you want to add the note to.<br>Here this should be `account`. | |
| `account-name` | string | true | The name of the account that you want to add the note to. | |
| `content` | string | true | The content of the note. | |

### Remove the private note from an account

```
enbas remove --type note --from account --account-name @name@example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to remove.<br>Here this should be `note`. | |
| `from` | string | true | The resource you want to remove the note to.<br>Here this should be `account`. | |
| `account-name` | string | true | The name of the account that you want to remove the note from. | |

## Follow requests

### View your follow requests

Prints a list of accounts that are requesting to follow you.

```
enbas show --type follow-request
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `follow-request`. | |
| `limit` | integer | false | The maximum number of accounts to print. | 20 |

### Accept a follow request

```
enbas accept --type follow-request --account-name @person.example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to accept.<br>Here this should be `follow-request`. | |
| `account-name` | string | true | The name of the account that you want to accept. | |

### Reject a follow request

```
enbas reject --type follow-request --account-name @person.example.social
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to accept.<br>Here this should be `follow-request`. | |
| `account-name` | string | true | The name of the account that you want to reject. | |

## Statuses

### View a status

### Create a status

- Create a one line status
- Create a status from a file
- Create a status with a poll

### Delete a status

_Not yet supported_

### Boost (Repost) a status

To boost a status you simply add a `boost` to it.

### Un-boost (Un-repost) a status

To un-boost a status that you've boosted you simply remove the `boost` from it.

### Like a status

To like (favourite) a status you simply add a `like` or a `star` to it.

### Unlike a status

To unlike (un-favourite) a status that you've previously liked you simply remove the `like` or `star` from it.

### Mute a status

_Not yet supported_

### Unmute a status

_Not yet supported_

## Polls

### Create a poll

See [Create a status](#create-a-status).

### View a poll

Prints the poll information to the screen.

```
enbas show --type poll --poll-id 01J0CEEZBZ6E6AYQSJPHCQYBDA
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `poll`. | |
| `poll-id` | string | true | The ID of the poll that you want to view. | |

### Vote in a poll

Add your vote(s) to a poll.

```
enbas add --type vote --to poll --poll-id 01J1TVJ705VV3VP02FVVBSMX7E --choose 3
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to add.<br>Here this should be `vote`. | |
| `to` | string | true | The resource you want to add the vote to.<br>Here this should be `poll`. | |
| `poll-id` | string | true | The ID of the poll you want to add the votes to. | |
| `choose` | int | true | The ID of the option that you want to vote for.<br>You can use this flag multiple times to vote for more than one option if the poll allows multiple choices. | |

## Lists

### Create a list

```
enbas create --type list --list-title "My Favourite People" --list-replies-policy list
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to create.<br>Here this should be `list`. | |
| `list-title` | string | true | The title of the list that you want to create. | |
| `list-replies-policy` | string | false | The policy of the replies for this list.<br>Valid values are `followed`, `list` and `none`. | list |

### View a list of your lists

```
enbas show --type list
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `list`. | |

### View a specific list

Prints the information of the specified list to screen along with all the accounts added to it (if any).

```
enbas show --type list --list-id 01J1T9DWR20DC36QWZFKHWZJ3H
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `list`. | |
| `list-id` | string | false | The ID of the list you want to view. If this is not specified then a list of your lists will be printed instead. | |

### Edit a list

Edits the title and/or the replies policy of a list.

```
enbas edit --type list --list-id 01J1T9DWR20DC36QWZFKHWZJ3H --list-title "My Favourite People (in the world)"
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to edit.<br>Here this should be `list`. | |
| `list-title` | string | false | The title of the list that you want to edit. | |
| `list-replies-policy` | string | false | The policy of the replies for this list that you want to change to.<br>Valid values are `followed`, `list` and `none`. | |

### Delete a list

Deletes a list.

```
enbas delete --type list --list-id 01J1T9DWR20DC36QWZFKHWZJ3H
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to delete.<br>Here this should be `list`. | |
| `list-id` | string | true | The ID of the list you want to delete. | |

### Add accounts to a list

Adds one or more accounts to a list.

```
enbas add --type account --account-name @name@example.social --account-name @person@mastodon.example --to list --list-id 01J1T9DWR20DC36QWZFKHWZJ3H
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to add.<br>Here this should be `account`. | |
| `account-name` | string | true | The name of the account you want to add to the list.<br>Use multiple times to specify multiple accounts. | |
| `to` | string | true | The resource you want to add the accounts to.<br>Here this should be `list`. | |
| `list-id` | string | true | The ID of the list that you want to add the accounts to. | |

### Remove accounts from a list

Removes one or more accounts from a list.

```
enbas remove --type account --account-name @person@mastodon.example --from list --list-id 01J1T9DWR20DC36QWZFKHWZJ3H
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to add.<br>Here this should be `account`. | |
| `account-name` | string | true | The name of the account you want to remove from the list.<br>Use multiple times to specify multiple accounts. | |
| `to` | string | true | The resource you want to remove the accounts from.<br>Here this should be `list`. | |
| `list-id` | string | true | The ID of the list that you want to remove the accounts from. | |

## Timelines

### View a timeline

Prints a list of statuses from a timeline.

- View your home timeline.
   ```
   enbas show --type timeline --timeline-category home
   ```
- View a maximum of 5 statuses from your instance's public timeline.
   ```
   enbas show --type timeline --timeline-category public --limit 5
   ```
- View a timeline from one of your lists.
   ```
   enbas show --type timeline --timeline-category list --list-id 01J1T9DWR20DC36QWZFKHWZJ3H
   ```
- View a timeline from a hashtag.
   ```
   enbas show --type timeline --timeline-category tag --tag caturday
   ```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `timeline`. | |
| `timeline-category` | string | false | The type of timeline you want to view.<br>Valid values are `home`, `public`, `list` and `tag`. | home |
| `list-id` | string | false | The ID of the list you want to view.<br>This is only required if `timeline-category` is set to `list`. | |
| `tag` | string | false | The hashtag you want to view.<br>This is only required if `timeline-category` is set to `tag`. | |
| `limit` | integer | false | The maximum number of statuses to print. | 20 |

## Media

### View media from a status

## Bookmarks

### View your bookmarks

Prints a list of statuses that you have bookmarked.

```
enbas show --type bookmarks
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to view.<br>Here this should be `bookmarks`. | |
| `limit` | integer | false | The maximum number of bookmarks to show. | 20 |

### Add a status to your bookmarks

```
enbas add --type status --status-id 01J17FH1KD9CN6J9Q01011NE0D --to bookmarks
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to add.<br>Here this should be `status`. | |
| `status-id` | string | true | The ID of the status. | |
| `to` | string | true | The resource you want to add the status to.<br>Here this should be `bookmarks`. | |

### Remove a status from your bookmarks

```
enbas remove --type status --status-id 01J17FH1KD9CN6J9Q01011NE0D --from bookmarks
```

| flag | type | required | description | default |
|------|------|----------|-------------|---------|
| `type` | string | true | The resource you want to remove.<br>Here this should be `status`. | |
| `status-id` | string | true | The ID of the status. | |
| `from` | string | true | The resource you want to remove the status to.<br>Here this should be `bookmarks`. | |

## Notifications

_Not yet supported_