Interactive TUI¶

tidydots includes an interactive terminal UI built with Bubble Tea and styled with Lipgloss. The TUI provides a visual way to browse, edit, and manage your dotfiles configuration without memorizing CLI commands.

Launching the TUI¶

There are two ways to start the interactive interface:

# Launch directly (no arguments)
tidydots

# Or use the -i flag with any command
tidydots restore -i
tidydots backup -i
tidydots install -i

Running tidydots with no arguments opens the full TUI experience. Using -i with a specific command opens the TUI focused on that operation.

Main screen¶

The main screen displays a table view of all your applications and their entries. Each row shows:

• Application name and description
• Entry names (configs and packages) nested under their application
• Status indicators showing the current state of each entry

Status indicators¶

For config entries with an explicit files list, “listed” means only the selected .tmpl source names participate in template status. An entry with an empty files list is a folder entry; its templates are discovered recursively.

Navigation¶

tidydots uses vim-style keybindings alongside arrow keys for navigation.

Core keybindings¶

Adding items¶

Pressing a opens an entry-type chooser before the edit form:

• Folder symlink links an entire backup directory to its target.
• File symlink links selected files from a backup directory.
• File copy deploys selected files as real copies instead of symlinks.
• Setup command runs an OS-specific command when its read-only check fails.

Use up/k and down/j to choose a type, enter to continue to the form, or esc to cancel. The form's type controls remain editable before saving.

Sorting¶

Press a sort key to sort by that column. Press the same key again to reverse the direction.

Search and filter¶

Press / to enter search mode. Type to filter applications and entries by name, description, target paths, or backup paths. The list updates in real time as you type. Press enter to confirm or esc to exit search mode (your selections are preserved).

Press f to toggle the filter. When enabled (the default), applications excluded by their application-level when expression are hidden. When disabled, those applications are shown. Entries excluded by their own when are removed before table filtering and remain absent in either mode.

Press x to toggle the action filter. It keeps applications with an uninstalled package and entries whose state needs attention (Missing, Ready, Adopt, Needs setup, Outdated, Check failed, Modified, or Unavailable). The filter composes with search and the f platform filter. If enabling it would hide selected items, tidydots asks for confirmation; answer y to enable it or n to leave the current view and selections unchanged. Confirming does not clear selections. A Check failed entry is actionable for visibility and diagnosis, but its setup command is not run until the check can safely determine the current state.

The TUI can start with this filter already enabled by running tidydots --actions. This keeps the normal interactive behavior while showing actionable work as soon as status checks settle.

A package is considered installed only when its main package and all dependencies in its installation plan are installed. Missing dependencies keep the application visible in the action filter, even if the main package is already present. The plan includes dependencies from all eligible standard managers, matching installation behavior.

Package status is automatically rechecked after installs using a fresh installed-package snapshot. Press ctrl+r on the clean main list to manually refresh all package, config, template, and setup statuses. The refresh preserves filters, selections, expansion, and cursor position; existing loading indicators show progress while statuses are rechecked.

The paging and jump motions operate only on the clean main list, not while search or a confirmation dialog is active. gg is a two-key sequence: press g twice. A single g waits for the second key and any other key cancels that pending sequence. Empty and one-row tables remain clamped safely.

Mouse support¶

Two-phase editing¶

All text fields in the TUI use a two-phase editing approach. This prevents accidental edits while navigating.

Phase 1: Navigation mode¶

When you navigate to a text field, it is focused but not editable. You can see the field is highlighted, but typing does not modify its value. Use ↑/k and ↓/j to move between fields.

Phase 2: Edit mode¶

Press enter or e to enter edit mode. The field becomes active and shows a text cursor. Type to modify the value.

• Press enter to save your changes and return to navigation mode
• Press esc to cancel your changes and return to navigation mode

Multi-selection¶

The TUI supports selecting multiple items for batch operations.

Selecting items¶

• Selecting an application automatically selects all its visible sub-entries (configs and packages)
• Deselecting an application deselects all its sub-entries
• Sub-entries can be individually toggled even when their parent application is not selected

Selection banner¶

When items are selected, a banner appears at the top of the screen showing the count:

2 app(s), 5 item(s) selected

Selections persist across search filtering, screen navigation, and edit operations.

Clearing selections¶

Press esc to clear all selections. The esc key follows a priority system:

1. If in search mode, esc exits search first (selections are kept)
2. If selections exist, esc clears all selections
3. Otherwise, esc returns to the previous screen

Batch operations¶

With items selected, you can perform operations on all of them at once. Each batch operation follows a three-screen flow.

Available operations¶

Three-screen flow¶

Every batch operation proceeds through three screens:

1. Select screen (main screen)

Browse and select the items you want to operate on. Use tab or space to toggle selections.

2. Summary screen

After pressing an operation key (r, R, i, or d), a summary screen appears showing exactly what will be changed. Restore (r) preserves manual edits to rendered templates through the normal merge. Force Restore (R) always asks for confirmation before proceeding and discards those edits. Review the list of operations, then:

• Press y or enter to confirm and proceed
• Press n or esc to cancel and return to the main screen

3. Progress screen

Once confirmed, a progress screen shows real-time feedback as each operation executes. A progress bar tracks completion.

4. Results popup

When the operation finishes, a popup overlay appears showing all results (success or failure for each item). Press enter or esc to dismiss. Press m from the main screen to re-open the results at any time. If results exceed the popup height, scroll with ↑/k and ↓/j.

Example workflow¶

1. Launch tidydots: tidydots
2. Navigate to the applications you want to restore
3. Press tab on each application to select it
4. Press r to start batch restore, or R for Force Restore when rendered-template edits should be discarded
5. Review the summary of deployments to be made
6. Press enter to confirm
7. Watch the progress bar as deployments are applied

Editing applications and entries¶

Edit an application¶

Navigate to an application row and press e to open the edit screen. You can modify:

• Name -- the application identifier
• Description -- optional description text
• When -- conditional expression for machine filtering

If hostname choices are configured at the top level of tidydots.yaml, focusing When and pressing enter or e opens a chooser. Use space or tab to select one or more hosts. Press enter or e to apply the selection without saving the form, or s / ctrl+s to apply it and save immediately. The chooser also provides Type expression for manual Go-template input. For example, selecting desktop generates:

when: '{{ eq .Hostname "desktop" }}'

Selecting desktop and laptop generates:

when: '{{ or (eq .Hostname "desktop") (eq .Hostname "laptop") }}'

Editing package dependencies¶

When editing an application's packages section, you can manage dependencies for any standard package manager:

1. Navigate to the packages section of the application form
2. Move to a native package manager entry (e.g., winget, apt)
3. Press p to open the dependency editor for that manager
4. Use the list editor to add, edit, or delete dependencies:
5. ↑/k, ↓/j to navigate
6. enter or e to edit an item or add a new one
7. d or delete to remove a dependency
8. esc to exit the dependency editor
9. Dependencies are shown as a count indicator on the manager row: winget: sxyazi.yazi (3 deps)

Edit a config entry¶

Navigate to a config entry and press e to edit. Editable fields include:

• Name -- entry identifier
• Backup -- path in your dotfiles repo (supports template expressions)
• Targets -- OS-specific target paths (linux, windows; supports template expressions)
• Files -- specific file list (empty means entire folder)
• Sudo -- toggle for elevated privileges
• Copy files -- toggle for method: copy, which deploys real files instead of symlinks
• When -- optional Go-template condition for this individual entry

The Copy files toggle only appears when an explicit file list is set, because copy mode is files-only. Switching an entry back to whole-folder mode therefore clears it.

The TUI resolves backup and targets with the same template and path rules as the command line. Invalid expressions and expansions that result in an empty path are shown as errors; they are never treated as literal or fallback deployment paths. Use . when you intentionally select the repository root for backup.

Focusing the sub-entry When field and pressing enter or e opens the same hostname chooser used for applications when hostnames are configured in tidydots.yaml. Use space or tab to select hosts and confirm to generate a condition, or choose Type expression for manual Go-template input. The generated condition is saved on that entry, so it combines with the parent application's condition.

Edit a setup entry¶

Navigate to an entry and press e, then toggle Setup entry. The form exposes paired Check and Run fields for Linux and Windows, Check mode, Sudo, and When. The When editor and hostname chooser work the same way as for config entries. Each OS must have both commands or neither, and at least one OS must be configured. Save writes the check, run, optional check_mode, and optional when values to tidydots.yaml. A setup entry cannot also have backup or target fields. You can run it from the TUI with r and delete it with d.

The Check mode selector is setup-only. It displays exit-code when check_mode is omitted, preserving the legacy behavior where exit 0 means applied and any nonzero exit means setup is needed. Use ←/h to choose exit-code, →/l to choose status, or space/enter to toggle between them. An untouched omitted value remains omitted when the form is saved. In status mode, exit codes 0, 1, and 2 mean Set up, Needs setup, and Outdated; 3 or higher is Check failed. See the status-code table for the complete contract.

Check commands must remain read-only and fast because they run during every TUI state refresh; see Setup Entries.

Edit custom and URL packages¶

In an application's Packages section, move below the standard managers to Custom or URL download and press enter to add or open that section. Use ↑/k and ↓/j to move through its fields, e or enter to edit a text field, and enter to confirm the text. esc cancels the current field edit; s or ctrl+s saves the application form. Press d, delete, or backspace on the section row to remove the complete custom or URL section and its values.

Custom packages require at least one Linux or Windows command. URL packages require both a URL and an install command for each OS where either value is supplied; use {file} in the command for the downloaded file path. Command fields (including installer and setup commands) are unbounded text areas and preserve pasted multiline content and tabs. Invalid partial sections are rejected when saving rather than written to the repository.

File picker¶

When editing the files list of a config entry, you have two ways to add files:

Browse Files mode

1. Navigate to the files field and press enter
2. Select "Browse Files" from the menu
3. An interactive file browser opens, starting in the target directory
4. Navigate with ↑/↓ or k/j, toggle file selection with space or tab
5. Selected files are highlighted with a purple background
6. Press enter to confirm your selections
7. Files are automatically converted to relative paths

Type Path mode

1. Navigate to the files field and press enter
2. Select "Type Path" from the menu
3. Type the relative file path directly
4. Press enter to confirm

List field navigation¶

When editing a list field (like files), the field has its own internal cursor:

• ↑/k and ↓/j navigate within the list
• At the top or bottom of the list, navigation moves to adjacent form fields
• enter or e on a list item enters edit mode for that item
• enter or e on the "Add" button starts adding a new item
• d, delete, or backspace removes the selected item

Saving changes¶

Press s or ctrl+s to save your changes to the tidydots.yaml configuration file. The TUI writes back to the same file it loaded from.

When launched with -n / --dry-run, adding, editing, and deleting applications or entries is preview-only. The TUI reports the proposed config change and does not write tidydots.yaml or mutate its loaded configuration. Deleting an application's final entry removes the application only when it has no package definition; package-only applications are retained.

Template diff & edit¶

When a config entry uses templates (.tmpl files) and you have manually edited the generated output, the entry shows a Modified status in blue. For method: copy, this check reads the live suffix-free target file; it does not use a .tmpl.rendered cache. A changed source or missing render history shows Outdated. If the source or target cannot be read safely, the entry shows Unavailable in red and is included by the action filter.

For an entry with a files list, status and diff discovery inspect only listed .tmpl source names; an unlisted template does not affect the row. List the .tmpl source name (not its suffix-free target name) to render and deploy a single template. Template status checks never request sudo interactively. Run the TUI in an appropriately authorized environment when protected content is unavailable.

Viewing diffs¶

1. Navigate to a sub-entry row showing Modified status
2. Press i to launch the diff viewer
3. If the entry contains multiple modified template files, a picker appears -- select the file you want to inspect
4. Your editor opens with two panes:
   • Left pane: A unified diff showing your edits (read-only); copy-mode diffs read the real deployed target
   • Right pane: The .tmpl source file (editable)
5. Edit the template to backport your changes, then save and quit your editor
6. The TUI resumes and refreshes the entry status

Editor detection¶

tidydots automatically detects the best way to launch the editor:

Help text¶

Context-sensitive help is displayed at the bottom of each screen. The help text updates based on your current state:

• In navigation mode: shows navigation and action keys
• In edit mode: shows save and cancel keys
• In selection mode: shows available batch operations

Practical examples¶

Restore specific configs interactively¶

tidydots restore -i

1. Browse the list of applications and config entries
2. Select the ones you want to restore with tab
3. Press r to restore
4. Review the summary and confirm

Install packages interactively¶

tidydots install -i

1. Browse applications that have packages configured
2. Select which applications to install packages for
3. Press i to install
4. Review the summary showing which packages and managers will be used
5. Confirm to proceed

Add a new application via TUI¶

1. Launch tidydots
2. Press A to add a new application
3. Fill in the name, description, and when expression
4. Press a to add config entries with backup paths and targets
5. Press s to save the configuration

Next steps¶

• Multi-Machine Setups -- conditional configs with when expressions
• Package Management -- package installation details
• System Configs -- managing files requiring sudo