docsreference

Commands

Every ttheme command, with its arguments, actions and options. This page is made from the same source as ttheme help all, so the two never disagree.

on this page

This tab
use
pin
unpin
pins
New tabs
default
on
off
config
auto
light
dark
Palettes
add
update
marketplace
Your own
new
edit
check
palette
share
Setup
init
uninstall
Support
info

ttheme help <command> prints one of them in your terminal, and ttheme <command> --help does the same without running it. A bare ttheme opens Preview and Browse.

This tab

`use`

ttheme use <palette>

Use a palette in this tab — a unique prefix works: ttheme use ho

guide: This tab, new tabs and the default

`pin`

ttheme pin [dir|ssh:<host>]

Pin a palette to a directory or an ssh host — the pin covers everything below it, or its whole repository; cd or ssh in repaints, leaving restores

guide: Pin to a folder or ssh host

`unpin`

ttheme unpin [dir|ssh:<host>]

Drop a pin — this directory's, every one below it, the one above that covers it, or an ssh host's

guide: Pin to a folder or ssh host

`pins`

ttheme pins

Map every pin as a file tree — the pinned directories in their palettes' colors, every ssh host, and the pin that covers this one

guide: Pin to a folder or ssh host

New tabs

`default`

ttheme default <palette>

Make a palette the one new tabs open with

guide: This tab, new tabs and the default

`on`

ttheme on

Use the default palette in new tabs again

guide: This tab, new tabs and the default

`off`

ttheme off

Take the palette and picture off every tab — the terminal's own colors until ttheme on

guide: This tab, new tabs and the default

`config`

ttheme config

Edit settings in $EDITOR — a new mode reaches every open tab, the rest apply in new tabs

guide: This tab, new tabs and the default

`auto`

ttheme auto

Show every palette in the mode the system is in — following it as it changes, where a wired Ghostty, iTerm2, kitty or WezTerm reports it

guide: Light, dark and auto

`light`

ttheme light

Show every palette in its light mode — every open tab repaints, and new tabs open in it

guide: Light, dark and auto

`dark`

ttheme dark

Show every palette in its dark mode — every open tab repaints, and new tabs open in it

guide: Light, dark and auto

Palettes

`add`

ttheme add [--in <marketplace>] <palette...>

Install palettes — from your marketplaces, from a share link (ttheme add https://ttheme.dev/builder/tt4:…), or from a palette file, which joins your local marketplace: ttheme add ~/Downloads/kisara.toml

--in <marketplace>: The local marketplace a palette file goes into — when you have more than one

guide: Share a link

`update`

ttheme update [marketplace...]

Update ttheme and refresh your marketplaces — official palettes come with ttheme; an installed palette from another marketplace keeps its colors until ctrl+r on it in Browse takes its update

guide: Add and update palettes

`marketplace`

ttheme marketplace [--owner <handle>] <action> [source]

Add or drop a marketplace — Browse also finds them on GitHub and switches their auto-update; init makes one of your own

add <source>: Add a marketplace — a repository (alice/ttheme-pastel, #v1 pins a tag or branch), a folder, or official; asks whether it updates on its own
remove <marketplace>: Drop one by its name (alice@pastel) — the palettes you installed from it keep working
init [name]: Make a marketplace of your own — <you>@<name>, in ~/.config/ttheme/marketplace/<name> or a folder you give
check [dir]: Check a marketplace's folder before you push it — ttheme-marketplace.toml, every palette, the renames and the contrast checks; nothing is written

--owner <handle>: init: your GitHub handle, when gh is not logged in and there is no terminal to ask in

guide: Add and update palettes

Your own

`new`

ttheme new [--from <palette>] [--in <marketplace>] <name>

Make a palette of your own in the palette editor — <you>@<marketplace>/<name>, from blank, installed at once

--from <palette>: Start from this palette's colors instead of blank
--in <marketplace>: The local marketplace to put it in — when you have more than one

guide: Your own palette

`edit`

ttheme edit [palette]

Change a palette in the palette editor — your own in its file, any other as your tuning over its marketplace's colors, which R and s in the editor put back; with none named, asks to edit the one this tab shows

guide: Tune a palette

`check`

ttheme check [--fix] [palette]

Check a palette against the contrast checks — where one fails, suggest colors that pass; with none named, asks to check the one this tab shows

--fix: Write the suggested colors into your palette

guide: Tune a palette

`palette`

ttheme palette [--json] [--preview] [--crop x,y,w,h] [--quant <n>] [--anchors <file>] [--catalog <name>] [--native <title>] [--lead <palette>] [--in <marketplace>] [--dry-run] <action> [arg]

Make a character's palette from colors measured on its official art — the steps the ttheme-palette agent skill takes, each printing JSON with --json

measure <file|url>: Count a picture's flat colors, or a box's with --crop — --preview writes a copy at most 800 px on its long side and reads the box in its pixels
consensus <tag>: Read which colors danbooru's posts of a character tag name — the eyes, an item, or none — to pick the parts that carry the identity
make [palette]: Turn an anchors file into palettes — ranks base schemes, harmonizes, fixes the ANSI roles and runs the contrast checks, then writes them into your local marketplace and installs them

--json: Print the result as JSON on stdout
--preview: measure: write a preview at most 800 px on its long side; --crop is then in its pixels
--crop x,y,w,h: measure: the box to count
--quant <n>: measure: group near-duplicate colors — a JPEG's, an antialiased edge's — into n levels a channel
--anchors <file>: make: the anchors file
--catalog <name>: make: the catalog folder the palettes go in
--native <title>: make: a new catalog's official title
--lead <palette>: make: the palette that stands for a new catalog
--in <marketplace>: make: your local marketplace to write into, or its folder
--dry-run: make: show the result and write nothing

Anchors file (--anchors), one entry per palette:

{

"bocchi": {

"slots": { "cursor": ["hair", "#ffb7c8"], "ansi4": ["eyes", "#7b96c8"], "ansi9": ["jacket", "#f39cbf"] },

"booru": "gotoh_hitori",

"native_names": ["後藤ひとり"],

"source": "https://…"

}

slots three colors in the order the character reads, the first the seed — background, foreground,

cursor, selection or ansi0–ansi15 — each ["<part>", "#rrggbb"] as measured

booru the danbooru tag ttheme find searches (optional)

native_names the names preview's search matches; left out, ttheme's name data fills them in (optional)

source where the colors were measured (optional)

With --json each action prints one object on stdout, its status done, unchanged or error;

an error lists each field it refuses in problems, as { path, problem }.

0: Done
1: Failed
2: Nothing changed — what it would write is already there
3: Invalid input — the message names the field and what it takes
4: A network request failed — try again

guide: Your own palette

`share`

ttheme share [--tone <tuned|original>] [palette]

Share palettes as a link or a GitHub marketplace — asks which and which palettes, then prints the link and its QR code; ttheme add <link> installs a link's palettes, pictures included, and ttheme marketplace add <owner>/<repo> adds the marketplace, which gh creates and sharing it again updates; a palette named, or a link into a pipe, shares that palette, or the one this tab shows, as a link without asking