Metadata-Version: 2.4
Name: tofuref
Version: 1.8.1
Summary: TUI for OpenTofu provider registry.
Project-URL: Homepage, https://github.com/DJetelina/tofuref
Project-URL: Repository, https://github.com/DJetelina/tofuref.git
Project-URL: Issues, https://github.com/DJetelina/tofuref/issues
Author: David Jetelina
License-Expression: MIT
License-File: LICENSE
Keywords: infra,opentofu,platform,sre,terraform,tofu,tool,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: anyio>=4.12.1
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: packaging>=25.0
Requires-Dist: platformdirs>=4.9.2
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: textual>=8.0.0
Requires-Dist: tomli>=2.2.1; python_full_version < '3.11'
Requires-Dist: yaucl>=0.2.0
Description-Content-Type: text/markdown

<div align="center">

# tofuref

[![opentrend.dev reach](https://opentrend.dev/badge/djetelina/tofuref/reach.svg)](https://opentrend.dev/)
[![PyPI - Version](https://img.shields.io/pypi/v/tofuref)](https://pypi.org/project/tofuref/)
[![AUR - Version](https://img.shields.io/aur/version/tofuref)](https://aur.archlinux.org/packages/tofuref)
[![Homebrew](https://img.shields.io/github/v/release/djetelina/homebrew-tap?filter=tofuref-*&label=brew)](https://github.com/djetelina/homebrew-tap)
![PyPI - License](https://img.shields.io/pypi/l/tofuref)
![GitHub Repo stars](https://img.shields.io/github/stars/DJetelina/tofuref?style=flat&logo=github)

A terminal UI for browsing the OpenTofu provider registry. Search providers and resources, read docs, copy `required_providers` blocks and code snippets — all without leaving the terminal.

![Screenshot](https://github.com/djetelina/tofuref/blob/main/tests/__snapshots__/test_snapshots/test_welcome.svg?raw=true)

</div>

## Installation

```bash
pipx install tofuref

# or with Homebrew
brew install djetelina/tap/tofuref

# or from AUR
yay -S tofuref
```

## Usage

```bash
tofuref
```

Jump straight to a resource (`-r`) or data source (`-d`):

```bash
tofuref -r keycloak_user
tofuref -d github_actions_environment_secrets
tofuref -r user -p mrparkers/keycloak
```

## Star History

<a href="https://www.star-history.com/?repos=djetelina%2Ftofuref&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=djetelina/tofuref&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=djetelina/tofuref&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=djetelina/tofuref&type=date&legend=top-left" />
 </picture>
</a>

<details>
<summary><strong>Controls</strong></summary>

### Actions

| keybindings   | action                                                                           |
|---------------|----------------------------------------------------------------------------------|
| `s`, `/`      | **search** in the context of providers and resources                             |
| `u`, `y`      | context aware copying (using a provider/resource)                                |
| `v`           | change active provider **version**                                               |
| `b`           | persistently bookmark an item to prioritize them in sorting when next re-ordered |
| `q`, `ctrl+q` | **quit** tofuref                                                                 |
| `t`           | toggle **table of contents** from content window                                 |
| `B`           | from content window, open active page in browser                                 |
| `ctrl+g`      | open **GitHub** repository for provider                                          |
| `ctrl+s`      | Show **stats** of provider's github repo                                         |

> Note: The GitHub functionality tries to use your GitHub token (env or `gh` cli) to avoid rate limiting.

### Focus windows

| keybindings               | action                     |
|---------------------------|----------------------------|
| `tab`                     | focus next window          |
| `shift+tab`               | focus previous window      |
| `p`                       | focus **providers** window |
| `r`                       | focus **resources** window |
| `c`                       | focus **content** window   |
| `backspace`, `left arrow` | focus previous window      |

### Navigate in a window

Navigate with arrows/page up/page down/home/end or your mouse.

VIM keybindings should be also supported in a limited capacity.

</details>

<details>
<summary><strong>Configuration</strong></summary>

Default configuration can be overridden by a config file,
which can be overridden with env variables.

Config file locations:

* Unix: `~/.config/tofuref/config.toml`
* macOS: `~/Library/Application Support"/tofuref/config.toml`
* Windows: `%USERPROFILE%\AppData\Local\tofuref\tofuref\config.toml`

### General

Put these as simple key=value in your config.toml.

| name                      | description                                                       | type  | default | env                                 |
|---------------------------|-------------------------------------------------------------------|-------|---------|-------------------------------------|
| http_request_timeout      | Timeout for all http requests (in seconds)                        | float | 3.0     | `TOFUREF_HTTP_REQUEST_TIMEOUT`      |
| index_cache_duration_days | How long the provider index should be cached for (in days)        | int   | 31      | `TOFUREF_INDEX_CACHE_DURATION_DAYS` |
| markdown_length_target    | Target markdown length (in characters) to keep tofuref responsive | int   | 40_000  | `TOFUREF_MARKDOWN_LENGTH_TARGET`    |

### Theme

These options belong to a toml section, `[theme]`.

| name          | description                                                                                                                          | type   | default                               | env                           |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------|--------|---------------------------------------|-------------------------------|
| ui            | Colorscheme for the UI, inspect available themes through command palette (`^p`) `Change theme` command                               | string | textual-dark (or `TEXTUAL_THEME` env) | `TOFUREF_THEME_UI`            |
| codeblocks    | **CURRENTLY WORKS ONLY IN COPY MENU** The [pygments style](https://pygments.org/styles/) for code blocks                             | string | material                              | `TOFUREF_THEME_CODEBLOCKS`    |
| borders_style | The borders to use for windows, list and showcase of available [here](https://textual.textualize.io/styles/border/#all-border-types) | string | ascii                                 | `TOFUREF_THEME_BORDERS_STYLE` |
| emoji         | Whether to display emojis or letters as icons                                                                                        | bool   | true                                  | `TOFUREF_THEME_EMOJI`         |

### Example file

Author's configuration:

```toml
[theme]
ui = "dracula"
codeblocks = "dracula"
borders_style = "vkey"
```

</details>

## Upgrade

```bash
pipx upgrade tofuref
```

<details>
<summary><strong>Development</strong></summary>

### Setup

    just init

### Testing

Run tests:

    just test

Update snapshots for tests if the diff was expected:

    just test-update

### Running

    just run

### Undocumented config options

Intended mainly for development.

Force downloading from API to see the first time load experience:

    TOFUREF_DISABLE_CACHE=1 uv run tofuref

Show popups with load times for provider/resource listings:

    TOFUREF_SHOW_LOAD_TIMES=1 uv run tofuref

Or combine those:

    TOFUREF_SHOW_LOAD_TIMES=1 TOFUREF_DISABLE_CACHE=1 uv run tofuref

</details>
