---
title: Import and export
description: Export providers to a TOML file without tokens, import that file on another machine, and add the tokens afterward.
---

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

## Export

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.

| Platform | Result |
|---|---|
| Desktop | A save dialog with the file type "TOML File" |
| Web | A browser download |
| iPhone | The system document picker, where the user chooses the destination |

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 format

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.

```toml
# 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](/docs/configuration) page explains that Pipedash does not read `PIPEDASH_TOKEN_<provider_id>` on its own.

## Use the file as config.toml

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](/docs/configuration) page covers the variables and the hot reload of `[providers]` blocks.

## Import

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.

| Outcome | Message |
|---|---|
| At least one provider added | Title "Providers imported". The message lists the added names and says "Add each token in the provider's edit dialog." |
| Providers skipped | The message adds "Skipped" and the names, with "already set up here" |
| Nothing added | Title "No providers imported" |
| Failure | Title "Couldn't import providers" with the reason |

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

### Tokens

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.

### Validation

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 API

The web server offers both actions on the [REST API](/docs/deployment/rest-api).

| Method | Path | Purpose |
|---|---|---|
| GET | `/providers/export` | Returns the TOML text as a JSON string |
| POST | `/providers/import` | Takes `{ "content": "<toml>" }` and returns the lists `added` and `skipped` |