Import and export

Settings, Providers exports all providers to one TOML file and imports such a file on another machine. The file never contains tokens.

ExportCopy Anchor Link

The "Export" button sits in the header of Settings, Providers. On iPhone the same action is the "Export providers" row. The control stays disabled while no provider exists.

The file is named pipedash-providers.toml. Where it goes depends on the platform.

A successful export shows the message "Providers exported. Tokens are not in the file. Set each token variable on the other machine." Cancelling the dialog or the picker shows no message.

File formatCopy Anchor Link

The file holds the same [providers] blocks as config.toml, in the order of the provider ids. A comment header tells the reader that the file has no tokens.

# Pipedash providers export.
# Tokens are not included. Set each token variable in the environment or enter the token in Settings > Providers.

[providers."GitHub OSS"]
type = "github"
token = "${PIPEDASH_TOKEN_GITHUB_OSS:-}"
refresh_interval = 60

[providers."GitHub OSS".config]
base_url = "https://github.com"
selected_items = "hcavarsan/pipedash"

Each token value is a ${VAR:-} reference. The reference expands to an empty string while the variable is unset, so the file loads without errors.

Pipedash picks the variable name in this order:

1. A provider whose stored token is a ${VAR} reference, such as ${CI_TOKEN}, keeps that variable name.
2. Any other provider gets PIPEDASH_TOKEN_ plus its name in upper case, with each run of other characters turned into _.
3. A name that is already taken gets the suffix _2, _3 and so on, so two providers never share a variable.

A provider name without letters or digits becomes PIPEDASH_TOKEN_PROVIDER. The PIPEDASH_TOKEN_ prefix is only a naming convention. The Configuration page explains that Pipedash does not read PIPEDASH_TOKEN_<provider_id> on its own.

Use the file as config.tomlCopy Anchor Link

The exported file loads as a startup config on another machine. Set each token variable in the environment of that machine and point PIPEDASH_CONFIG_PATH at the file. The Configuration page covers the variables and the hot reload of [providers] blocks.

ImportCopy Anchor Link

The "Import" button sits next to "Export". On iPhone the row is "Import providers". A file picker accepts .toml files.

Import adds only the providers that are not set up yet. Pipedash matches each table key of the file against the names of the existing providers and skips every match. The result of an import lists both groups.

An added provider keeps its name, refresh_interval and config values.

TokensCopy Anchor Link

Import never reads tokens. It parses the file without variable interpolation, so a ${VAR} reference or a literal token in the token key has no effect. Every added provider starts with an empty token.

The user enters the token in the edit dialog of each added provider.

ValidationCopy Anchor Link

Pipedash checks the whole file before it adds anything. These cases fail the import with no change.

• Parse error: the file is not valid TOML. The message starts with Couldn't read the providers file.
• No providers: the file has no [providers] entries.
• Unknown type: a block has a type that no plugin handles. The message names the table key and the type.

Import writes to the database and does not change config.toml.

Web APICopy Anchor Link

The web server offers both actions on the REST API.