Skip to main content
Version: 0.4.2

tinct files

Track and manage files generated by tinct.

Synopsis​

tinct files <subcommand> [flags]

Description​

Every file tinct writes is recorded in a manifest, along with the plugin that produced it and a checksum of the content. The files command is how you inspect that manifest, check whether anything has drifted, bring pre-existing files under tinct's management, and clean up after plugins you've removed.

Subcommands​

CommandDescription
listShow all tracked files
verifyCheck tracked files against their recorded checksums
adoptBring existing files into the manifest under a plugin
deleteDelete tracked files and drop them from the manifest
orphansList files whose plugin is no longer available
cleanDelete orphaned files from disk

list, verify and delete accept --plugin <name> to narrow the operation to a single plugin.

tinct files list​

Display all files currently tracked by tinct:

tinct files list

# Only one plugin's files
tinct files list --plugin kitty

Example output​

File                               Plugin  Size    Updated
---------------------------------  ------  ------  ----------------
~/.config/kitty/themes/tinct.conf  kitty   3.2 KB  2026-07-01 11:05

tinct files verify​

Check that tracked files still match the checksums recorded when tinct wrote them. This is how you find files that have been edited by hand or clobbered by another tool:

tinct files verify
tinct files verify --plugin niri

Output flags each discrepancy and ends with a summary:

MODIFIED: ~/.config/niri/tinct-colours.kdl
MISSING: ~/.config/wofi/tinct-colours.css

Verified: 36, Modified: 2, Missing: 6

verify exits non-zero when anything is modified or missing, so it works in a dotfile health-check script.

tinct files adopt​

Bring configuration files that already exist under tinct's management. Useful when you've been maintaining a colour file by hand and want tinct to take over. Both the plugin name and the file(s) are required:

tinct files adopt hyprland ~/.config/hypr/colors.conf
tinct files adopt waybar ~/.config/waybar/tinct.css
tinct files adopt kde-plasma ~/.local/share/color-schemes/*.colors

Once adopted, a file is tracked like any other — tinct will overwrite it on the next generate rather than skipping it.

tinct files delete​

Delete generated files and remove them from the manifest:

# Specific files
tinct files delete ~/.config/hypr/colors.conf

# Everything from one plugin
tinct files delete --plugin kde-plasma

# Skip the confirmation prompt
tinct files delete --plugin kde-plasma --force

This removes the files from disk, not just from tracking.

tinct files orphans​

List files left behind by plugins that are no longer available — typically external plugins you've since deleted:

tinct files orphans
Plugin: opencode (not available)
  ~/.config/opencode/themes/tinct-light.json

tinct files clean​

Delete every file orphans reports, and drop them from the manifest:

tinct files clean
tinct files clean --force

Manifest file​

Tinct stores tracking information in ~/.local/share/tinct/manifest.json:

{
  "version": "1",
  "created_at": "2026-02-19T18:50:32Z",
  "updated_at": "2026-07-01T11:05:14Z",
  "files": {
    "/home/me/.config/kitty/themes/tinct.conf": {
      "plugin": "kitty",
      "created_at": "2026-02-19T18:50:32Z",
      "updated_at": "2026-07-01T11:05:14Z",
      "checksum": "sha256:b3e856e0f39217ec9b00a47c718143bdd5fe191922eb9352cb2878523f516946",
      "size": 3277,
      "action": "modified"
    }
  }
}

Why tracking matters​

Avoiding conflicts​

When tinct generates a file, it:

  1. Checks if the location is already tracked
  2. If tracked, overwrites with new content
  3. If not tracked, checks if the file exists
  4. If it exists and is not tracked, skips it (unless --force)

This prevents accidentally overwriting files you wrote yourself. Skipped files are reported on stderr:

Skipping ~/.config/kitty/kitty.conf: file exists but is not tracked by tinct

Clean regeneration​

When you switch themes, tracked files are safely updated:

# First theme
tinct generate -i image -p ~/wallpaper1.jpg -o all

# Switch theme - tracked files are updated
tinct generate -i image -p ~/wallpaper2.jpg -o all

Customising generated output​

Tracked files are overwritten on every run, so hand-editing one is temporary — tinct files verify will report it as MODIFIED, and the next generate will discard your changes.

To make a change stick, edit the plugin's template instead:

tinct plugins templates dump -o kitty
# edit ~/.config/tinct/templates/kitty/tinct.conf.tmpl

Tinct picks up custom templates automatically. See templating.

Examples​

Audit what tinct owns​

tinct files list
tinct files verify

Remove one plugin's output entirely​

tinct files delete --plugin kitty --force

Clean up after removing an external plugin​

tinct plugins delete opencode
tinct files orphans
tinct files clean

Force overwrite untracked files​

tinct generate -i image -p ~/wallpaper.jpg -o all --force

See also​