Client plugins and configuration¶
The tsuru command-line client can be extended with plugins and tuned through a few files and environment variables. This page covers both.
Plugins¶
A plugin is any executable file placed under ~/.tsuru/plugins. When you run tsuru <name> ... and <name> is not a built-in command, the client looks for an executable called <name> (with or without extension) in that directory, either directly or inside a <name>/ subdirectory, and runs it with the remaining arguments.
A plugin wins a name conflict with the built-in shorthands (deploy, rollback, log, info, shell), but a user-defined alias is expanded before any lookup, so it wins over both. Public plugins are tagged tsuru-plugin on GitHub.
Installing, listing and removing¶
$ tsuru plugin install <plugin-name> <plugin-url>
$ tsuru plugin list
$ tsuru plugin remove <plugin-name>
plugin install downloads the URL into ~/.tsuru/plugins. The download may be:
| Content | Behaviour |
|---|---|
| A single script or binary | Saved as ~/.tsuru/plugins/<plugin-name> and made executable. The remote file name does not matter. |
A .tar.gz or .zip archive |
Extracted to ~/.tsuru/plugins/<plugin-name>/. It must contain an executable named <plugin-name> (extension optional). |
A manifest.json |
tsuru picks the archive for the current GOOS/GOARCH from UrlPerPlatform and installs it as above. |
Reinstalling replaces the previous copy.
Installing a bundle¶
$ tsuru plugin bundle --url <bundle-url>
The URL must serve a JSON document listing plugins to install in one go:
{"plugins": [{"name": "rpaasv2", "url": "https://example.com/rpaasv2/manifest.json"}]}
Each entry goes through the same logic as plugin install. The command prints which plugins succeeded and fails if any did not.
What a plugin receives¶
The plugin inherits your whole environment plus these variables:
| Variable | Value |
|---|---|
TSURU_TARGET |
The current target URL. |
TSURU_TOKEN |
Your authentication token. |
TSURU_PLUGIN_NAME |
The name the plugin was called by. |
TSURU_VERBOSITY |
Set when --verbosity was passed or the variable was already set. |
TSURU_TABLE_COLOR, TSURU_TABLE_UTF8 |
The table border colour and UTF-8 setting in effect, so plugin tables match. |
NO_COLOR |
Set to 1 when colours are disabled. |
TSURU_PAGER |
Set when a pager is configured (see below). |
The global flags --target, --verbosity and --config are parsed before the plugin runs and exported as TSURU_TARGET, TSURU_VERBOSITY and TSURU_CONFIG_FILE; everything else goes to the plugin untouched. A plugin that runs tsuru itself does not recurse: a plugin cannot invoke a plugin of its own name.
Writing a plugin¶
Any language works. A minimal shell plugin:
$ cat > ~/.tsuru/plugins/hello <<"EOF"
#!/bin/sh
echo "Hello from ${TSURU_PLUGIN_NAME}, target ${TSURU_TARGET}, args: $@"
EOF
$ chmod +x ~/.tsuru/plugins/hello
$ tsuru hello world
To talk to the API, send Authorization: bearer $TSURU_TOKEN to $TSURU_TARGET. To distribute a compiled plugin for several platforms, publish a manifest.json:
{
"SchemaVersion": "1.0",
"Metadata": {"Name": "myplugin", "Version": "1.0.0"},
"UrlPerPlatform": {
"linux/amd64": "https://example.com/myplugin_linux_amd64.tar.gz",
"darwin/arm64": "https://example.com/myplugin_darwin_arm64.tar.gz"
}
}
The full guide lives in the client repository: Developing Tsuru Plugins.
Targets¶
A target is a tsuru API endpoint with a label. Targets live in ~/.tsuru/targets; the current one is in ~/.tsuru/target and its token in ~/.tsuru/token.d/<label>.
$ tsuru target add <label> <url> [-s]
$ tsuru target list
$ tsuru target set <label>
$ tsuru target update <label> <url> [-s]
$ tsuru target remove <label>
-s/--set-current makes the new or updated target the current one. TSURU_TARGET and TSURU_TOKEN, when set, take precedence over the files, which is how CI jobs and plugins run without a tsuru login.
Command aliases¶
Since client 1.38.1 you can define shortcuts for commands:
$ tsuru config alias "app deploy" "deploy"
$ tsuru deploy myapp
$ tsuru config alias "app info" "ai"
$ tsuru ai myapp
$ tsuru config alias "app info" -d # remove the alias
The first argument is the real command, the second the alias; both may contain spaces. An alias is expanded before anything else, so it can override a built-in command or a plugin of the same name. Aliases are stored as JSON in $HOME/.config/tsuru/config.json. Point the client at another file with the global --config <path> flag or the TSURU_CONFIG_FILE environment variable.
Note
tsuru config --help mentions a TSURU_CONFIG_PATH variable; the client actually reads TSURU_CONFIG_FILE.
Output settings¶
Output options are read from ~/.tsuru/client.yaml or from environment variables named TSURU_<KEY> with dashes turned into underscores (pager becomes TSURU_PAGER).
| Key | Effect |
|---|---|
disable-colors |
Turn colours off. The standard NO_COLOR variable, a dumb terminal or a non-terminal stdout do the same. |
color-stream |
Colour streamed output such as deploy logs. Defaults to on in a modern terminal. |
pager |
false disables paging; a string such as less -R sets the pager command. Default: less -RFX, used only when stdout is a terminal and the output is taller than it. |
table-utf8 |
Use UTF-8 box-drawing borders in tables. Defaults to on in a modern terminal. |
table-color |
Colour of table borders, e.g. hi-black, blue. |
tab-writer, tab-writer-padding, tab-writer-truncate, break-any, force-wrap |
Table layout tweaks (tab-aligned columns instead of borders, padding, truncation, wrapping). |
# ~/.tsuru/client.yaml
pager: false
disable-colors: true
Commands that support machine-readable output take --json; check each command's reference page. --verbosity 1 prints the HTTP requests the client makes and --verbosity 2 also prints the responses.
Self-update checks¶
| Variable | Effect |
|---|---|
TSURU_CLIENT_FORCE_CHECK_UPDATES |
true forces the version check even when it was done recently. It blocks if the release server does not answer. |
TSURU_CLIENT_SELF_UPDATE_SNOOZE_DURATION |
Suppress the update check for a duration such as 72h. |
TSURU_CLIENT_IGNORE_OUTDATED_PCLOUD_REPO |
true silences the warning about an outdated packagecloud repository on deb/rpm installs. |
Shell completion¶
$ tsuru completion bash > /etc/bash_completion.d/tsuru
$ tsuru completion zsh > "${fpath[1]}/_tsuru"
$ tsuru completion fish > ~/.config/fish/completions/tsuru.fish
$ tsuru completion powershell | Out-String | Invoke-Expression
--no-descriptions drops the help text from the generated script. Completion scripts for the four shells are documented under tsuru completion.