toot-tooi 0.21.2
Mastodon terminal user interface
Requires Python: >=3.11

tooi
====

<!-- https://commons.wikimedia.org/wiki/File:Britannica_Horn_Modern_Horn.png -->
![Horn logo](horn.jpg)

tooi is a text-based user interface for Mastodon, Pleroma and friends. The name
is a portmanteau of [toot](https://toot.bezdomni.net/) and
[TUI](https://en.wikipedia.org/wiki/Text-based_user_interface).

tooi is a re-implementation of the TUI included with
[toot](https://toot.bezdomni.net/) using the modern and more powerful
[Textual](https://textual.textualize.io/) framework.

* Source code: https://codeberg.org/ihabunek/tooi
* Python package: https://pypi.org/project/toot-tooi/ \*
* IRC chat: #toot channel on libera.chat

\* Could not get `tooi` as Python project name, if someone knows python people
ask them kindly to approve
[this request](https://github.com/pypi/support/issues/3097).

This project proudly uses [Pride Versioning 🏳️‍🌈](https://pridever.org/).

## Screenshot

![tooi screenshot](tooi.jpg)

## Project status

This project is still being actively developed. While we aim to keep the project
usable at all times, expect that things may change before we hit version 1.0.

## Installation

If possible, install tooi from your OS package repository.

<details>
  <summary>Packaging status</summary>
  <a href="https://repology.org/project/tooi/versions" style="display: block; margin-top: 2rem">
    <img src="https://repology.org/badge/vertical-allrepos/tooi.svg?columns=4" alt="Packaging status" />
  </a>
</details>

Otherwise, follow one of the options below.

### Using uv

The recommended method of installation is using [uv](https://docs.astral.sh/uv/)
which installs python projects into their own virtual environments.

1. Follow the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/)
   to set it up.

2. Install tooi:
   ```
   uv tool install toot-tooi
   ```

3. Upgrade tooi to the latest version:
   ```
   uv tool upgrade toot-tooi
   ```

### Using pipx

The second recommended option is using [pipx](https://pipx.pypa.io/stable/)
which is similar to uv but somewhat slower.

1. Follow the [pipx installation guide](https://pipx.pypa.io/stable/installation/)
   to set it up.

2. Install tooi:
   ```
   pipx install toot-tooi
   ```

3. Upgrade tooi to the latest version:
   ```
   pipx upgrade toot-tooi
   ```

### From the Python Package Index

Alternatively, if you know what you're doing, install tooi from
[pypi](https://pypi.org/project/toot-tooi/) using your favourite method.

## Usage

Launch the program by running `tooi`.

Run `tooi --help` to see the available commandline options.

On first login tooi will offer an account selection screen where you can log
into your instance.

## Key bindings

Context-specific key bindings are shown in the footer of the screen. You can
also press `?` to toggle the help panel which shows all available bindings.

Here's a possibly outdated overview of key bindings:

General bindings:

* Arrow keys or `h`/`j`/`k`/`l` - move up/down/left/right
* `Tab` and `Shift+Tab` - move between focusable components
* `Space` or `Enter` - activate buttons and menu items
* `Ctrl+p` - open the command palette

Managing tabs:

* `.` - refresh timeline
* `/` - open search tab
* `1` - `9` - switch between open tabs
* `Ctrl+d, Ctrl+w` - close current tab
* `g` - open new tab ("goto")

Status bindings:

* `a` - show account
* `b` - boost status
* `d` - delete status
* `e` - edit status
* `f` - favourite status
* `m` - show media
* `r` - reply to status
* `s` - reveal sensitive
* `t` - show thread
* `u` - show toot source
* `v` - open toot in browser

## Image support

By default tooi will attempt to render images in your console using
[Terminal Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
or [Sixel](https://en.wikipedia.org/wiki/Sixel) graphics, and falling back to
half-block images.

Whether images can be displayed depends on your terminal. Check out the list of
[known supported terminals](https://github.com/lnqs/textual-image?tab=readme-ov-file#supported-terminals).

To see if your terminal supports graphics, you can run `tooi --env` and look at
the "Image support" section, e.g.:

```md
## Image support

TGP (Kitty) images: True
Sixel images: False
Is TTY: True
Default: tgp
```

## Setting up a dev environment

Usage of [uv](https://docs.astral.sh/uv/) for development is recommended.

Check out tooi and install the dependencies:

```
git clone https://codeberg.org/ihabunek/tooi.git
cd tooi
uv sync
```

Run the app by invoking:

```
uv run tooi
```

## Using the console

To use the
[Textual console](https://textual.textualize.io/guide/devtools/#console), run
it in a separate terminal window:

```
uv run textual console
```

Then run tooi in dev mode so it connects to the console:

```
uv run textual run --dev tooi.cli:main
```

## Code style and linting

Rule of thumb: look at existing code, try to keep it similar in style.

This project uses `ruff` to format code. Please run it on any modified files
before submitting changes: `ruff format <path>`

## Type checking

This project is configured to use
[pyright](https://github.com/microsoft/pyright) for type checking, and I
recommend that you install the pyright language server if it's available for
your editor. Currently it returns errors in some places, some of which are
caused by the way textual is implemented. So it's not required to have zero
errors before submitting patches, but it will indicate problems in new code.