![flowrs_logo](./image/README/1683789045509.png)

[![CI](https://github.com/jvanbuel/flowrs/actions/workflows/ci.yml/badge.svg)](https://github.com/jvanbuel/flowrs/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/flowrs-tui.svg)](https://crates.io/crates/flowrs-tui)
[![Downloads](https://img.shields.io/crates/d/flowrs-tui.svg)](https://crates.io/crates/flowrs-tui)
[![License](https://img.shields.io/crates/l/flowrs-tui.svg)](https://github.com/jvanbuel/flowrs/blob/main/LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.87.0-blue)](https://github.com/jvanbuel/flowrs)
[![Built With Ratatui](https://ratatui.rs/built-with-ratatui/badge.svg)](https://ratatui.rs/)

Flowrs is a TUI application for [Apache Airflow](https://airflow.apache.org/). It allows you to monitor, inspect and manage Airflow DAGs from the comforts of your terminal. It is build with the [ratatui](https://ratatui.rs/) library.

![flowrs demo](./vhs/flowrs.gif)

## Installation

You can install `flowrs` via Homebrew if you're on macOS / Linux / WSL2:

```
brew install flowrs
```

or by downloading the binary directly from GitHub:

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jvanbuel/flowrs/releases/latest/download/flowrs-tui-installer.sh | sh
```

Alternatively, you can build `flowrs` from source with `cargo`:

```bash
cargo install flowrs-tui --locked
```

## Usage

### Managed Airflow services

The easiest way to user `flowrs` is with a managed Airflow service. The currently supported managed services are:

- [x] Conveyor
- [x] Amazon Managed Workflows for Apache Airflow (MWAA)
- [x] Google Cloud Composer
- [x] Astronomer

To enable a managed service, run `flowrs config enable -m <service>`. This will add the configuration for the managed service to your configuration file, or prompt you for the necessary configuration details. On startup `flowrs` will then try to find and connect to all available managed service's Airflow instances.

Note that for Astronomer, you need to set the `ASTRO_API_TOKEN` environment variable with your Astronomer API token (Organization, Workspace or Deployment) to be able to connect to the service.

### Custom Airflow instances

If you're self-hosting an Airflow instance, or your favorite managed service is not yet supported, you can register an Airflow server instance with the `flowrs config add` command:

![flowrs config add demo](./vhs/add_config.gif)

This creates an entry in your configuration file at `$XDG_CONFIG_HOME/flowrs/config.toml` (following the XDG Base Directory Specification, which defaults to `~/.config/flowrs/config.toml`). For backwards compatibility, flowrs also reads from `~/.flowrs` if the XDG location doesn't exist. If you have multiple Airflow servers configured, you can easily switch between them in `flowrs` configuration screen.

Flowrs supports authenticating with HTTP Basic Auth or using bearer tokens. When selecting the bearer token option, you can either provide a static token or a command that generates a token.

### Themes

Flowrs ships with six themes, including four [Catppuccin](https://github.com/catppuccin/catppuccin) flavors. The active theme is configured with `flowrs config --theme <theme>`:

| Theme | Description |
|---|---|
| `auto` | Detects your terminal background and picks dark or light (default) |
| `dark` | Dark theme |
| `light` | Light theme |
| `catppuccin-latte` | Catppuccin Latte (light) |
| `catppuccin-frappe` | Catppuccin Frappé (medium-dark) |
| `catppuccin-macchiato` | Catppuccin Macchiato (dark) |
| `catppuccin-mocha` | Catppuccin Mocha (darkest) |