Skip to content

Ruff Config Inspection

ruff-sync includes an experimental Terminal User Interface (TUI) for exploring and interrogating your project's Ruff configuration.

Experimental Feature

The Ruff Config Inspection TUI is currently experimental. It may undergo rapid architectural changes, be refactored, or be removed entirely in upcoming versions. Use with the understanding that the interface and behavior are not yet stable.

📸 Overview

The Ruff Config Inspection TUI provides a structured, interactive view of your tool.ruff configuration, allowing you to browse effective rules, search the full Ruff rule registry, and view detailed documentation for any rule or configuration key.

Ruff-Sync TUI Main View The main TUI view — Pyflakes (F) selected in the sidebar, showing a colorful mix of Enabled, Ignored, and Disabled rule statuses in the registry table.

🚀 Getting Started

🚀 Installation

The TUI components are optional to keep the base ruff-sync package lightweight. To use the inspection features, install ruff-sync with the tui extra.

Persistent Tool Installation 

uv tool install "ruff-sync[tui]"

One-off Invocation 

uvx --with "ruff-sync[tui]" ruff-inspect

Project Development 

uv add --dev "ruff-sync[tui]"


pipx install "ruff-sync[tui]"

pip install "ruff-sync[tui]"

Usage

You can launch the TUI using either the inspect subcommand or the dedicated ruff-inspect entry point:

ruff-sync inspect

ruff-inspect

If you are working in a specific directory or want to point to a different pyproject.toml, use the --to flag:

ruff-inspect --to path/to/project

✨ Key Features

🌳 Configuration Tree

The left sidebar provides a hierarchical view of your local Ruff configuration. Selecting a node (like lint or format) filters the rule registry to show only relevant settings and rules.

🔍 Rule Registry & Inspector

The upper-right table displays the rules currently effective in your project. Each rule shows its code, name, and status (e.g., explicitly enabled via select or ignored).

When you select a rule, the Rule Inspector at the bottom-right fetches and displays the full documentation for that rule, including its rationale and code examples.

Ruff Rule Details Detailed inspection of a specific Ruff rule within the TUI.

⚡ Global Rule Search (Omnibox)

Press / at any time to open the Omnibox. This allows you to perform a fuzzy search across the entire Ruff rule registry, even for rules not currently active in your project.

Ruff Rule Search Fuzzy concept search in the Omnibox — searching "import" surfaces matching rules across multiple linter families simultaneously.

⌨️ Keyboard Shortcuts

Key Action
q Quit the application.
/ Open the Global Search (Omnibox).
? or l Show the Legend / Help modal.
c Copy the current inspector content to the clipboard.
Enter Select a node or rule to inspect.
Tab Move focus between the tree, table, and inspector.
Esc Close the current modal or search.

TUI Keyboard Help The interactive Legend modal showing all available keyboard shortcuts.