Config CLI

rimz config reads and edits the per-machine config: three commented TOML files under the RimZ home, ~/.rimz/, that you own and can edit by hand. rimz list-themes and rimz list-pets print the choices for the two settings with many values, theme.scheme and theme.pets.pet. What each key means, the merge order, and the project config tier are in the configuration guide.

rimz config init [--force] [--print]
rimz config path
rimz config get [KEY] [--json]
rimz config set <KEY> <VALUE>
rimz list-themes [--json]
rimz list-pets [--json]

A refusal or error exits 1, following the CLI-wide exit codes; the global flags are defined there too.

Provider prompt-cache lifetimes are configurable through rimz config set harness.prompt_cache_ttl.claude 5m (or off). The provider kind must be built-in or installed as a plugin; durations must exceed one minute. rimz config set harness.cache_keepalive false disables waiting-agent cache pings, and rimz config set harness.cache_keepalive_max 2h (default 6h, or off) stops them that long after the agent's last request of its own. Defaults and idle-compaction timing are in idle compaction.

The config files

The directory is $RIMZ_HOME, or ~/.rimz/ when RIMZ_HOME is unset; rimz paths prints it with every other location. A dotted key's first segment decides which file rimz config set writes.

Two key families land under a different table than their dotted name suggests. theme.colors.* lands in the root [colors.*] tables of theme.toml, so an Alacritty palette pasted there keeps working. loop.* drops the loop. prefix inside loop.toml, so loop.default-timeout is the file's top-level default-timeout.

The same directory holds remote.toml (SSH room aliases, managed by rimz remote) and agents/, subagents/, teams/, traits/, and skills/ (Markdown definitions and the shared skill library). rimz config get includes loaded definitions; set does not edit their source files.

Write the templates

rimz config init           # write all three files
rimz config init --print   # print the templates, write nothing

init writes the shipped template for each of the three files and prints wrote <path> for each. Every template line is commented, so a fresh file follows the defaults; rimz config init --print is the complete, current list of keys and defaults.

init --force is the clean reset. To refresh existing files against newer templates and keep your values, run rimz setup, which merges instead.

Print the config path

rimz config path prints the resolved path of config.toml, whether or not the file exists. The other three files sit beside it.

$ rimz config path
/home/me/.rimz/config.toml

Read a value

rimz config get loads the effective config (the three files layered over built-in defaults, plus profiles and teams from ~/.rimz/) and prints it. It reads strictly: a file with a TOML or validation error fails the command with that error instead of falling back to defaults.

$ rimz config get sidebar.focus_key
Alt+p
$ rimz config get theme.scheme
error: config key `theme.scheme` is unset

A key RimZ knows but that has no stored value and no printed default fails with config key `KEY` is unset and exit 1. Several optional keys whose default is resolved at runtime answer this way until you set them, among them theme.scheme, theme.mode, and loop.default-timeout; the template shows their defaults. A key RimZ does not know fails with unknown config key `KEY`, and a key with an empty segment (theme..scheme) fails with config keys use non-empty dotted segments.

Set a value

rimz config set <KEY> <VALUE> changes one key in its owning file and prints set <KEY>. It runs these steps, and stops without writing at the first one that fails:

1. Parses the value (rules below) and rejects a key RimZ does not know, so a typo never lands in the file.
2. Reads the owning file, or starts from its template when the file does not exist.
3. Checks the value against the key's type and format.
4. Sets the key in place: it uncomments the file's commented line for the key when there is one and otherwise adds the key, keeping every other line and comment as it was.
5. Validates the whole resulting file.
6. Writes the file atomically (a temporary file renamed over the original).

rimz config set theme "Catppuccin Mocha"                # theme.scheme in theme.toml
rimz config set theme.pets.enabled true                 # a TOML boolean
rimz config set notifications.triggers '["waiting", "failed"]'
rimz config set theme.display.context_meter.red '{ percent = 90, tokens = 400000 }'

To undo a change, set the old value again, or delete the line from the file to return to the default.

How the value is parsed

A value that parses as a TOML value is written as that value (80, true, ["a", "b"], an inline table); anything else is written as a string (fresh, Catppuccin Mocha). Quote a string that would otherwise parse as another type, such as '"true"'.

These keys always take a string, so 200k, 50/day, or a theme named 0x96f needs no extra quoting:

The two shorthands write the full key: rimz config set theme <name> sets theme.scheme, and rimz config set theme.glyphs <set> sets theme.glyphs.set.

What set refuses

Strict configuration loads reject the retired idle-compaction timer key and idle_compact values auto or always with a removed-key error directing you to rimz setup, or to remove the timer and set harness.idle_compact to on, off, or a duration. The retired timer is no longer a get or set key. See setup's repair for preserving current preferences. Lenient runtime loads retain the usual whole-file fallback to built-in defaults when the file is invalid.

Keys that do more than write

Three keys check or change the machine beyond the file.

agents.isolation sandbox probes bubblewrap before writing. On Linux it looks for bwrap on PATH and runs a trivial command inside a bubblewrap mount view; on any other OS, with bwrap missing, or when the probe fails (commonly unprivileged user namespaces disabled by sysctl or AppArmor), the command prints the reason and leaves config.toml unchanged. host, the default, runs no probe. The setting applies to later launches, restarts included; running panes keep the isolation they started with. The per-launch --isolation flag on rimz agents, rimz teams, rimz subagents, and rimz agents fork takes precedence, and what isolation changes is in security.

remote_control.claude and remote_control.codex switch the provider's remote-control host on the running machine. Setting either to true checks the host's preconditions first and refuses with the fix when they fail. After the write, claude adds or closes the claude remote-control pane in every running room's rimzd view, and codex starts or stops the shared Codex remote-control daemon. A hand edit reaches Claude hosts on the rimzd view's next repair pass, but for Codex it changes only what later room starts do, so use set to start or stop a running daemon. rimz start refuses a blocked host with its fixes and, in a terminal, offers to run without it for this run; that choice is recorded on the room and never changes config.toml. What each host runs is in the remote guide.

List themes

rimz list-themes prints the bundled Alacritty theme names, sorted. Each name works as the value of rimz config set theme.scheme <name>; quote a name with spaces.

$ rimz list-themes | head -3
0x96f
12-bit Rainbow
3024 Day

Custom scheme files and color slots are in the theming guide.

List pets

rimz list-pets lists every pet id you can give theme.pets.pet: the built-in pets first, then each pet installed under ~/.codex/pets/ (a directory holding pet.json), sorted by directory name. An installed pet's id is that directory name.

A built-in id wins a collision: install a petdex pet named rocky and theme.pets.pet = "rocky" still selects the built-in, so reach the installed one by its directory path instead. RimZ resolves the setting in order: a built-in id, then an http:// or https:// selector as a remote sprite sheet, then a selector containing / or . or starting with ~ as a local path, and anything else as an installed pet's directory name.

On a machine with no installed pets:

$ rimz list-pets --json
[
  "codex",
  "dewey",
  "fireball",
  "rocky",
  "seedy",
  "stacky",
  "bsod",
  "null-signal"
]

The terminal preview fetches each built-in sprite sheet over HTTPS into ~/.rimz/cache/pets/v1/assets/ on first use and reads installed pets from disk. With RIMZ_PETS_OFFLINE=1 it reads the cache only. A pet that cannot load leaves an empty slot, and the grid ends with (some pets unavailable - check network, or RIMZ_PETS_OFFLINE serves cache only); the command still exits 0. Render tiers, custom sheets, and petdex installs are in the pets guide.