Plugin file reference
This page lists where nuvem looks for plugins.toml, every key the file
accepts, the input types, and the template fields each service offers.
Write a plugin walks through a first plugin.
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 --plugins <path>. nuvem never looks for the
plugin file beside a file named by --config. nuvem info prints the path it
read and how many plugins loaded.
nuvem loads no plugins from a file that any user on the machine can write
(chmod o-w plugins.toml fixes it), from something that is not an ordinary
file, or from a file over 1 MiB.
Example
Section titled “Example”version = 1 # schema version; missing = 1; unknown = whole file rejected
[[plugins]]id = "describe" # unique within a scope; names the plugin in warningsscope = "compute" # one service, from the same vocabulary [aliases]/[columns]/[[jumps]] usekey = "d" # press `,` then this to run it on the selected rowlabel = "Describe {name}" # palette entry and confirmation heading; templatedargs = ["compute", "instances", "describe", "{name}", "--zone", "{zone}"]dangerous = false # true adds a typed acknowledgement to the confirmation
[[plugins]]id = "delete-instance"scope = "cloudsql"key = "D"label = "Delete instance {name}"args = ["sql", "instances", "delete", "{name}"]dangerous = trueFile layout
Section titled “File layout”| key | required | meaning |
|---|---|---|
version |
no (1) |
schema version. Any value other than 1 rejects the whole file. |
plugins |
no | the array of plugins, written [[plugins]] once per plugin. [plugins] with single brackets is not an array and is rejected. |
Any other top-level key, such as [[plugin]], is reported as a typo.
Plugin fields
Section titled “Plugin fields”| field | required | meaning |
|---|---|---|
id |
yes | unique within a scope; names the plugin in warnings |
scope |
yes | one service, from the same vocabulary [aliases] uses |
key |
yes | a single printable, non-space character, pressed after , to run this plugin; unique within a scope |
label |
yes | palette entry and confirmation heading; templated |
args |
yes | one string per argument, each templated independently. These are the arguments gcloud receives. The program is not one of them. |
dangerous |
no (false) |
adds a typed acknowledgement to the confirmation |
inputs |
no (none) | values you supply when the plugin runs; see Typed inputs |
args is an array of strings, never one string. Splitting a string needs a
shell parser, and there is no shell anywhere on this path. Each element is
templated independently and becomes exactly one argument. The program is
not part of args: it is always gcloud. nuvem adds
--configuration <active-config> in front of your args.
Two plugins in one scope cannot share an id or a key. The same key in two
different scopes is fine, because only one scope is in view at a time.
Input fields
Section titled “Input fields”Each [[plugins.inputs]] table declares one value the plugin asks for. See
Typed inputs for how the prompt behaves.
| field | required | meaning |
|---|---|---|
name |
yes | the {field} this input fills: a letter or _, then letters, digits or _. It cannot repeat a field of the plugin’s scope. |
type |
yes | one of the input types below |
choices |
for dropdown |
non-empty list of strings; only a dropdown takes it |
default |
no | must match type, and be one of choices for a dropdown |
Input types
Section titled “Input types”| type | the prompt shows | accepts |
|---|---|---|
string |
a text field | any non-empty text |
number |
a text field | a finite number, such as 0.5 or 200 |
integer |
a text field | a whole number, such as 200 or -3 |
bool |
a two-state choice, changed with ←/→ |
sends the text true or false; starts at false without a default |
dropdown |
a choice from choices, changed with ←/→ |
one of choices |
Template fields
Section titled “Template fields”label and every args element can contain {field} placeholders. The
fields that exist depend on scope. The list is the same one
Jump rules use, plus the names of the
plugin’s own inputs. nuvem rejects a field the scope does not have when the
file loads, with a warning that names it. For example, {zone} under
scope = "cloudsql" is rejected, because Cloud SQL rows have a region, not a
zone.
A template renders whatever the row holds, so the flag you pair it with must
be right for every row in that service. Persistent disks are the case to watch.
compute disks list returns zonal and regional disks in one table, so a disks
plugin’s {location} is sometimes a zone and sometimes a region. If you pair
it with a fixed --zone, the plugin fails on every regional disk.
Problems
Section titled “Problems”nuvem checks each plugin on its own. It drops a plugin with a problem, with a
warning that names its index, and the others still load. A problem in the file
itself (unreadable, not TOML, an unknown version) loads no plugins, with one
warning. Your config.toml is unaffected either way. See
Config problems.
Plugins are read once, at startup. To pick up a change, restart nuvem.
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.