Your config file

rta needs no configuration, and a machine that never has one works: the dashboard builds itself, output is pretty at a terminal, and an agent reaches only what needs no grant. The config file is where you change that for yourself. It is one YAML file holding preferences (the default output format, the dashboard, the colours, a plugin's own settings) and, beside them, your profiles and roles.

Nothing in it grants anything. A grant lives in its own sealed file and is issued by a person at a terminal, a plugin's approval lives in the trust record, and a credential never lives in a config file at all: secrets: holds the name of where one comes from. So a config file is safe to keep in a dotfiles repository, and a line in it can make rta quieter or louder but never make an agent more able.

Where it lives

On macOS and on Linux alike:

Where	When
$XDG_CONFIG_HOME/rta/config.yaml	When XDG_CONFIG_HOME is set to an absolute path
~/.config/rta/config.yaml	Otherwise
the file RTA_CONFIG names	Whenever it is set, over both of the above, which is what portable setups and test harnesses use

rta config path prints the real one for your shell, so a script or an editor never has to guess it:

rta config path

/home/you/.config/rta/config.yaml

A relative XDG_CONFIG_HOME is ignored, as the convention says. Builds before this one kept the file in ~/Library/Application Support/rta on macOS and read nothing from the new place: if you have a config left there, rta doctor has an old config row naming it and the mv that moves it, and every command at a terminal says so in one line until it is moved (a pipe and -o json stay quiet).

Look at it

rta config

FILE ───────────────────────────────────────────────────────────────────────────────────────
file    /home/you/.config/rta/config.yaml
exists  yes, 15 lines
from    $XDG_CONFIG_HOME/rta

SETTINGS ───────────────────────────────────────────────────────────────────────────────────
╭──────────────────────┬───────────────────────────────┬────────╮
│ KEY                  │ VALUE                         │ SOURCE │
├──────────────────────┼───────────────────────────────┼────────┤
│ dashboard.width      │ 6                             │ file   │
│ theme.primary        │ #7aa2f7                       │ file   │
│ dashboard.add        │ 1 tile — `rta dashboard list` │ file   │
│ plugins.http.timeout │ 10s                           │ file   │
╰──────────────────────┴───────────────────────────────┴────────╯

With no file it says so and that every key is at its default. rta config show is the same answer under a name that says what it does. A value an environment variable outranks names the variable in the SOURCE column and what the file says (RTA_OUTPUT (the file says json)), because a file that seems ignored is the first thing worth ruling out when output is not what you wrote.

Change one key

A key is named the way rta explain prints it: output, dashboard.width, dashboard.hidden, dashboard.order, theme.<slot>, theme.status and plugins.<plugin>.<key>. A setting several capabilities of a plugin share is one key (plugins.http.timeout), and one that a single capability reads is spelled with its name (plugins.sys.cpu.cores, which makes rta sys cpu draw every core). rta explain http.get lists the ones a capability reads and carries the line that sets one.

rta config set theme.primary '#7aa2f7'
rta config set dashboard.width 6
rta config set plugins.http.timeout 10s
rta config get plugins.http.timeout
rta config unset plugins.http.timeout

set answers with what it wrote and the line that undoes it:

wrote  set plugins.http.timeout to 10s in /home/you/.config/rta/config.yaml
back   `rta config unset plugins.http.timeout` returns it to its default, 30s

set holds the value to what the key takes, so a value no call would accept is refused here and not written to be refused on every call:

rta config set plugins.http.timeout 10

ERROR core.config.set.type plugins.http.timeout is declared duration, and takes a duration from 1s to 10m
HINT write it as `rta config set plugins.http.timeout 30s`

A length of time is written with its unit everywhere rta takes one, --timeout and the timeout keys included: 30s, 5m, 2h, 1d. A bare number does not say whether it counts seconds or minutes, so a flag, a config file or a profile that holds one is refused, and rta config check and rta doctor say so before a call does.

A key that takes a list takes one argument per element (rta config set dashboard.hidden gen.overview git.overview). Setting a key to what it already is writes nothing, so a line in a script that runs on every boot is safe. A name that is a block of keys and not one value (plugins, theme) is refused with the keys it holds, a misspelled key is answered with the nearest one, and --dry-run says what would be written without writing it.

Your comments stay. set, unset, rta dashboard add, rta profile set and the TUI all edit the file in place, so a note you wrote above a key is still above it afterwards, and a file with Windows line endings keeps them. Say the file holds this:

# halves suit my laptop; the monitor wants thirds
dashboard:
  width: 4

After rta config set dashboard.width 6 the number changes and the comment does not. A comment on a line a command removes goes with it, and a note directly above a block it removes too.

If RTA_OUTPUT is exported and you set output, the answer adds a line saying so, because the variable outranks the file and commands keep printing what it says until it is unset. A credential is never printed back: rta config get refuses a key that holds one (core.config.key.secret) and rta config show shows (redacted — a credential does not belong in this file), which is also the cue to move it into secrets: or the secret store.

Edit it by hand

rta config edit

It opens the file in $VISUAL, then $EDITOR, then vi, and holds what you save to the same checks as rta config check before it replaces the file. With no file yet it opens a starter with the common keys commented out, so nothing is stated until you uncomment a line:

# Uncomment what you want to change.
# output: json                  # the default --output: pretty, json, yaml, csv or md
#
# dashboard:
#   width: 6                    # how wide a tile is, in twelfths of the screen: 6 is half; left out, it follows the terminal
#   hidden: [gen.overview]      # tiles to leave off the screen
#
# theme:
#   primary: '#BA73DE'          # the ten palette slots; `rta config schema` names them
#   status: alerts              # all, alerts or off: how much of the green/amber/red that grades is drawn
#
# plugins:
#   http:
#     timeout: 10s              # `rta explain http.get` names each key a plugin reads

A file that does not parse reopens the editor with the reason and its line at the top, and leaving it as it is cancels. A key rta ignores is saved and named, with its line. rta config edit also keeps config.schema.json beside the file and points the file's first lines at it, so an editor that speaks yaml-language-server completes each key, flags an unknown one and explains it on hover; rta config schema prints the same JSON Schema for a file somewhere else. It needs a terminal (without one it says so and names rta config set and rta config path instead), and an editor that returns before you have saved loses the edit, so a windowed one needs its wait flag: EDITOR='code --wait'.

Check it

rta config check

╭──────┬──────────────┬────────────────────────────────────────────────────────────────────────────╮
│ LINE │ KEY          │ PROBLEM                                                                    │
├──────┼──────────────┼────────────────────────────────────────────────────────────────────────────┤
│   17 │ theme.primry │ not a color this rta understands — did you mean `primary`? (one of:        │
│      │              │ accent, bad, faint, good, ink, inverse, label, muted, primary, warn)       │
│   18 │ dashbord     │ is not a key rta reads (did you mean "dashboard"?)                         │
│   20 │ output       │ "jsno" is not an output format (it takes pretty, json, yaml, csv or md)    │
╰──────┴──────────────┴────────────────────────────────────────────────────────────────────────────╯

The colours are held to the same questions wherever they are written, a profile's own theme: included (profiles.shop-prod.theme.bad, with its line): a slot the palette does not have (with the one it nearly is), a colour that is not #rrggbb (an unquoted # is no value at all, and is said to be), and — for a profile's, and for a config file you did not name — a status colour, or status, the word that chooses how much of the grade colours is drawn, which only your own config file sets, a text colour too dim to be seen on a black or a white terminal, and a primary that is exactly a status colour, which the palette leaves out. A status that is none of all, alerts and off is said to be, with the three. A file is checked on its own, so a profile in a drop-in is judged against the colours of the file it is in, and rta doctor is the one that sees them all together.

A key rta does not read is ignored, which on its own would make a typo look like a setting that does nothing, so every command at a terminal warns about one and rta doctor has a config row for each with its line. rta config check exits 1 when it finds something and says has nothing rta ignores when it does not, so it fits a pre-commit hook. It names what a profile states and its calls never read as well — a set: line for a key every read takes as its scope, which a call names (a call names its scope). It holds the file and not the machine, so a profile that maps a credential onto the store passes whether or not this machine has made one: rta profile list and rta doctor say that a store is still to be made. A value output: cannot take is the one problem that stops commands: every command that renders fails as core.output.invalid and names the file, and rta doctor, rta config and rta config set output pretty still run so you can fix it.

Split it across files

When one file grows long — a profile per environment, a team's roles, the colours — put some of it in config.d, the directory beside the file: ~/.config/rta/config.d/ next to config.yaml, or <name>.d next to the file RTA_CONFIG names (mine.d beside mine.yaml). Every .yaml or .yml file in it is read after the file, in the order of its name, and says the same keys the file does:

# ~/.config/rta/config.d/20-dashboard.yaml
dashboard:
  width: 4
  add:
  - id: kube.overview
    profile: prod

Each thing is stated in one file. A profile, a role, one plugin's settings, the dashboard: block, the theme: block and output each live in a single file, and stating one twice is refused, naming both files, rather than settled by an order nobody wrote down. The alternative is a later file quietly changing where prod points for every command that follows, which is the one thing you could not see from either file alone. It costs nothing the split is for: a team's profiles in one file, an environment's in another, the dashboard and the colours in a third. A screen a profile writes in its own entry is part of the entry, so it is in the file that holds the profile, and each view under dashboard: views: is a unit of its own beside them.

A write goes where the thing lives. rta profile set prod, rta dashboard add, rta config set and the TUI edit the file that states what they change, with your comments kept, and put something nothing states yet in config.yaml. The answer names the file it wrote. rta config lists the drop-ins and the file each setting is in, rta config check checks every file, and rta config edit 10-prod opens one of them (a new one is created when you save), holding what you save to the same rule: a profile, role or block that another file already states is refused while you are still looking at it. A first line of # yaml-language-server: $schema=../config.schema.json gives a drop-in the completion the file has.

Only a file somebody named has a directory. The ./.rta.yaml rta falls back to when there is no config directory has none, for the reason it has no profiles and no dashboard: a cloned repository does not get to arrange what rta connects to. Only regular files are read, or a link to one, which is what a dotfiles manager makes of this directory; a name that starts with a dot, ends in ~ or is not .yaml or .yml is left alone, and at most 64 are read. Nothing in a drop-in grants anything, any more than a line of the file does, and the plugins' own sandbox keeps the directory from them as it keeps the file.

Lengths of time

A length of time is written one way wherever it is written: a number and a unit, 30s, 5m, 2h, 1d, 1w, or several together, 1h30m and 1d12h. The same words work in a profile's ttl:, a role's ttl: and a policy's maxTTL:, in a tile's, a section's or the screen's refresh:, in --ttl of a grant or a lock, in --for of rta use, in --since of a log, in rta time at (in 2d), and in a plugin's duration inputs. A day is twenty-four hours and a week seven, not calendar units. A bare number is refused everywhere, since 30 is the one spelling every reader has a different default for. What a place then allows is its own bound and is said in its own words: a grant lasts a day at most, so 3d is held to 1d, and a tile waits a day at most.

A first config that is good

Small, and stating only what you chose. The defaults are chosen to be the right ones (the automatic dashboard, the built-in colours, an agent that reaches only what needs no grant), and a key you state is a decision you made and a default that can no longer improve under you. A first file worth having is a few lines:

dashboard:
  width: 6
  add:
  - id: eol.watch
theme:
  primary: "#7aa2f7"
plugins:
  http:
    timeout: 10s

That is a dashboard of tiles half the screen wide with the version watchlist added to it, one accent colour, and a shorter timeout for rta http calls. Every line of it was one command: rta config set dashboard.width 6, rta dashboard add eol.watch, rta config set theme.primary '#7aa2f7' and rta config set plugins.http.timeout 10s. What does not belong in it: a credential (use secrets: and the store), a grant (rta grant allow), and a plugin's approval (rta plugin trust). The file says what is shown and how a connection is spelled, and the boundary says what an agent may do.

No tool on the MCP surface writes this file, and the path gate keeps the config directory out of an agent's reach: the file decides what is printed and which connections exist, so an agent that could write it could change its own limits.

Make the dashboard and the theme yours

Two commands each, and Dashboard and theme is the rest:

rta dashboard add eol.watch          # a tile the automatic set leaves out
rta dashboard hide git.overview      # one the automatic set draws, off your screen
rta dashboard list                   # every tile bare rta would draw, and where each came from
rta config set theme.primary '#7aa2f7'

In the TUI the same changes are keys: + adds a tile from the catalogue or a search match, H hides one, [ and ] move it, and t opens the colour editor. A tile you added from another terminal reaches an open dashboard on its next refresh.

Related

• Where rta keeps things — the config directory next to the data directory and every file in both
• Profiles — the profiles: block, which rta profile set writes for you
• Profiles in depth — the schema, in an editor

Next

Dashboard and theme — stating the dashboard in the file, and the colours.