Config file
nuvem reads an optional, versioned TOML configuration file. It holds your
presentation and navigation preferences: refresh cadence, the startup
service, sidebar visibility, theme, extra service aliases, rebindable
hotkeys, each service’s table columns and default sort, and the
related-resource jumps J offers. Nothing in this file can run a command.
Executable declarations live in a separate file,
plugins.toml. nuvem reads it only from your
platform config directory or from an explicit --plugins <path>. It never
reads it from the directory a --config path points at. A config.toml that
you were handed, synced, or checked into a repository thus cannot bring
commands with it.
Where it lives
Section titled “Where it lives”| Platform | Path |
|---|---|
| Linux | ~/ (or $XDG_CONFIG_HOME/) |
| macOS | ~/Library/Application Support/ |
To read a different file, pass --config <path>. The file is optional. If
there is no file, every setting keeps its built-in default.
nuvem refuses a file that is not an ordinary file (a named pipe, a directory) or is larger than 1 MiB, and reports why. nuvem follows a symbolic link, so dotfile managers work.
Precedence
Section titled “Precedence”Lowest to highest: built-in defaults, then the config file, then command-line flags. A flag always wins. Two settings exist in both places:
| Config key | Flag | How they combine |
|---|---|---|
general.poll_interval_secs |
--poll-interval |
The flag wins. |
general.read_only |
--read-only |
Either one turns read-only on. Neither can turn it off. |
Every other flag has no config key. See Command line.
Check what nuvem read
Section titled “Check what nuvem read”Run nuvem info to see the resolved config, plugin, log, and cache paths and
the active theme. It does not start the interface:
nuvem 0.1.0config: /home/dev/.config/nuvem/config.toml (loaded)plugins: /home/dev/.config/nuvem/plugins.toml (2 loaded)log: /home/dev/.cache/nuvem/nuvem.logcache: /home/dev/.cache/nuvemtheme: defaultconfig: reports loaded, not found, or error: <message> for a file that
exists but failed to parse. plugins: reports not found for a file that is
absent, which is the normal case. For a file that is present, it reports how
many entries loaded. You can thus tell a file nuvem never opened from one
that declares nothing. nuvem also prints any field-level warnings (see
Config problems) to stderr and lists them under
nuvem info.
Full example
Section titled “Full example”version = 1 # schema version; missing = 1; unknown = rejected
[general]poll_interval_secs = 5 # refresh cadence in seconds; 0 disables background refreshdefault_service = "gce" # fallback service for a configuration with no remembered view: "gce" | "gke" (restart-required)sidebar_visible = true # service navigator sidebar shown by defaulttheme = "default" # "default" | "no-color" | "high-contrast"read_only = false # refuse cloud-resource mutations (see Read-only mode); # OR'd with --read-only, so this can only turn it on
[aliases] # extra service aliases: alias -> service idvms = "gce"k8s = "gke"
[hotkeys] # rebindable normal-mode action -> single keyhome = "H"refresh = "R"
[favorites] # scopes to order first in the context pickerprojects = ["prod-project"] # matched against project idregions = ["europe-west1"] # matched against region namezones = ["europe-west1-b"] # matched against zone name
[theme.overrides] # frame color per gcloud configurationprod = "red" # configuration name -> border color
[theme.project_overrides] # frame color per project, whatever reaches itprod-project = "red" # project id -> border color
[columns.compute] # per-service table columns and default sortcolumns = ["name", "status", "zone", "machine-type"]sort = "status" # must be sortable and present in `columns`sort_direction = "desc" # "asc" (default) | "desc"; needs a `sort`
[[jumps]] # one related-resource jump `J` offersfrom = "compute" # source serviceto = "compute:network" # destination "<service>:<tab>"name = "{name}" # templated target name; default "{name}"location = "{zone}" # templated target zone/region; default: the row's ownlabel = "Network of {name}" # picker wording; default "<tab> of <name>"The table lists every key the file accepts. Each key links to the page that
explains it, except version, which this page covers. <service> is a
service ID from Services. <action> is
a hotkey action.
| Key | Type | Default | Allowed values |
|---|---|---|---|
version |
integer | 1 |
1. Any other value makes nuvem ignore the whole file. |
general.poll_interval_secs |
integer | 5 |
seconds; 0 turns background refresh off |
general.default_service |
string | "gce" |
gce, compute, compute_instances, gke, clusters, gke_clusters |
general.sidebar_visible |
boolean | true |
true, false |
general.theme |
string | "default" |
default, no-color, high-contrast |
general.read_only |
boolean | false |
true, false |
aliases.<alias> |
string | none | a service id, alias or label |
hotkeys.<action> |
string | each action’s own key | one character, or ctrl-<character> |
favorites.projects |
list of strings | [] |
project ids |
favorites.regions |
list of strings | [] |
region names |
favorites.zones |
list of strings | [] |
zone names |
theme.overrides.<configuration> |
string | none | a color |
theme.project_overrides.<project> |
string | none | a color |
columns.<service>.columns |
list of strings | the service’s built-in columns | column ids; must include name |
columns.<service>.sort |
string | "name" |
a sortable column id |
columns.<service>.sort_direction |
string | "asc" |
asc, desc |
jumps[].from |
string | required | a service id |
jumps[].to |
string | required | "<service>" or "<service>:<tab>" |
jumps[].name |
string | "{name}" |
a template |
jumps[].location |
string | the source row’s location | a template |
jumps[].label |
string | "<tab> of <name>" |
a template |
jumps[].select |
string | none | targets-this-instance |
plugins |
none | none | Not allowed here. Plugins belong in plugins.toml; nuvem warns and ignores them. |
nuvem reports any other key as unknown and ignores it. The rest of the file
still applies. A misspelled key such as poll_interval_sec is reported the
same way.
general.default_service, the starting gcloud configuration and the plugin
file take effect only at startup. Every other key can be applied with
Reload configuration.
nuvem is released under the MIT License. The source is on GitHub.
nuvem is an independent project, not affiliated with or endorsed by Google. Google Cloud is a trademark of Google LLC.