Deployment Options File

The deployment options file stores deployment settings for fivetran deploy, so you don't have to specify them every time you run the command. If you deploy to multiple connections or environments, you can organize their settings into named profiles within the same file and switch between them using --profile with the fivetran deploy command, without maintaining separate files or re-entering flags.

The deployment options file is supported in fivetran-connector-sdk v3.0.0 and later. In earlier versions, the CLI reused deployment settings previously saved on the server. Starting with v3.0.0, the CLI uses settings provided through CLI flags, environment variables, or a deployment options file instead.
The deployment options file requires Python 3.11 or later. If you run the CLI with Python 3.10, the CLI skips this file and resolves settings from CLI flags, environment variables, and built-in defaults only.

You can create a deployment options file manually. If you're upgrading from an earlier version and running Python 3.11 or later, the CLI automatically creates a file called options.toml with your previously saved settings on the first fivetran deploy run. For more details, see Automatic migration.

Create a deployment options file

If the CLI has already created a local file, open ~/.fivetran/connector_sdk/options.toml and edit it directly. Skip to step 2.

Create a file named options.toml in one of these locations:
- Project directory: To manage deployment settings for a specific project.
- ~/.fivetran/connector_sdk/: To make deployment settings available across projects.
If you use a different filename, the CLI won't recognize it automatically. Specify the custom path using --options-file when you run fivetran deploy, or set the FIVETRAN_OPTIONS_FILE environment variable. For example, fivetran deploy --options-file ~/.fivetran/connector_sdk/custom_settings.toml.

Add deployment settings using TOML section headers ([profile_name]) to define profiles. For the full list of deployment settings you can store in this file, see Supported deployment options.

[default]
python_version = "3.14"
naming = "FIVETRAN"

["group_id_a-connection_a"]
destination = "warehouse_a"
connection = "connection_a"
python_version = "3.11"
naming = "SOURCE"
proxy_id = "proxy-1"
proxy_host_config_key = "host-key-a"

Save the file.

The CLI automatically looks for options.toml in the supported locations when you run fivetran deploy. To use a file at a custom path, pass --options-file <path> or set the FIVETRAN_OPTIONS_FILE environment variable. See File discovery for the full search order.

The deployment options file is optional. You can provide deployment settings using CLI flags or environment variables instead. If you use this file, protect it using appropriate local file permissions. If your project uses version control, add this file to .gitignore to avoid accidentally committing connection settings.

Use profiles

A profile is a named group of deployment settings in the deployment options file. Each TOML section defines a separate profile.

In the preceding example, the file contains two profiles:

[default] contains shared settings used when you don't specify a profile.
["group_id_a-connection_a"] contains settings specific to a connection, including proxy configuration.

Use the default profile

When you run fivetran deploy without --profile, the CLI automatically uses [default], if it exists.

For example:

fivetran deploy --destination warehouse_a --connection connection_a

The CLI reads the Python version and naming strategy from [default]. By default, [default] doesn't contain destination or connection, so the example provides them using --destination and --connection. You can also provide them using the FIVETRAN_DESTINATION_NAME and FIVETRAN_CONNECTION_NAME environment variables, or add them to [default].

Select a named profile

Use --profile <name> to select a different profile.

For example, to deploy using the ["group_id_a-connection_a"] profile:

fivetran deploy --profile group_id_a-connection_a

The CLI reads the deployment settings from ["group_id_a-connection_a"] instead of [default].

You can also select a profile from a specific options file:

fivetran deploy --options-file ./configs/options.toml --profile group_id_a-connection_a

Profile behavior

Profiles are independent. A named profile doesn't inherit values from [default] or any other profile.
If a field is missing from the selected profile, the CLI continues through the remaining field resolution order. It doesn't look for the field in another profile.
If the specified profile doesn't exist, deployment fails and the CLI reports that the profile wasn't found.
If you specify a profile with --profile <name> and no deployment options file exists, deployment fails with the same error.
If [default] doesn't exist and you omit --profile, no profile is selected. The CLI resolves settings from other supported sources.

Profiles created during automatic migration are named <group_id>-<connection_name>. If a profile isn't found, or required options can't be resolved, and the file contains a migrated profile that matches your destination and connection, the CLI suggests using --profile to select it. See Automatic migration.

File discovery

When you run fivetran deploy, the CLI searches for the deployment options file in the following order and uses the first file it finds:

Path specified using --options-file <path>.
Path specified in the FIVETRAN_OPTIONS_FILE environment variable.
options.toml in the current directory.
options.toml in ~/.fivetran/connector_sdk/.

The CLI doesn't combine settings from multiple deployment options files.

If you specify a path using --options-file or FIVETRAN_OPTIONS_FILE and the file doesn't exist, deployment fails and reports the missing path. Deployment also fails if the selected file contains invalid TOML.

Supported deployment options

You can specify the following fields in a deployment options file profile to configure deployment settings:

Field	Type	Equivalent CLI flag	Description
`destination`	String	`--destination`	Destination name in your Fivetran account.
`connection`	String	`--connection`	Connection name in the destination.
`python_version`	String	`--python`, `--python-version`	Python runtime version, for example `"3.14"`.
`naming`	String	`--naming`	Naming strategy for the connection schema: `FIVETRAN` or `SOURCE`.
`hybrid_deployment_agent_id`	String	`--hybrid-deployment-agent-id`	ID of a custom Hybrid Deployment agent.
`proxy_id`	String	`--proxy-id`	Proxy Agent ID. `proxy_id` has no equivalent environment variable. If neither `--proxy-id` nor the selected profile provides a proxy ID, the CLI clears the Proxy Agent and routes the connection through direct networking. To keep using a Proxy Agent, add `proxy_id` to every profile that uses one, or pass `--proxy-id`.
`proxy_host_config_key`	String	`--proxy-host-config-key`	Key in `configuration.json` that contains the `host:port` endpoint. Only valid with `proxy_id`. Add `proxy_host_config_key` only if your `configuration.json` uses a custom key instead of the standard `host` or `hosts` keys.
`package_id`	String	`--package-id`	ID of an existing package to use for the connection. When set, the CLI reuses the package and skips uploading new code.

You cannot store the Fivetran API key in options.toml. Provide it using --api-key or the FIVETRAN_API_KEY environment variable. The CLI masks API keys in logs and error messages.

Example:

["group_id_a-connection_a"]
destination = "warehouse_a"
connection = "connection_a"
python_version = "3.11"
naming = "SOURCE"
hybrid_deployment_agent_id = "agent_id_a"

When you redeploy an existing connection, you must provide python_version explicitly through a CLI flag, environment variable, or a deployment options file profile. For a connection in a Hybrid Deployment destination, you must also provide hybrid_deployment_agent_id, including when the connection uses the destination's default agent. If you omit a required value, the deploy fails with a clear error that names the missing field. For new connections, the CLI uses the SDK built-in default Python version, and the destination's default agent where applicable.

If a profile contains an unsupported field or a misspelt field name, deployment fails with an error identifying that field. Remove or correct it in the file.

Automatic migration

When upgrading to Connector SDK v3.0.0, the CLI automatically migrates previously saved deployment settings from the server to a local options file.

Automatic migration does not run in the following cases:

You're running Python 3.10. The CLI skips the deployment options file and automatic migration and resolves settings only from CLI flags, environment variables, and built-in defaults.
A deployment options file already exists in any of the supported file discovery locations. If you manually create this file before your first deployment with the new CLI, it skips automatic migration.

For CI/CD deployment pipelines, you can skip automatic migration by setting the CI environment variable to true.

When automatic migration runs, the CLI:

Retrieves previously saved deployment settings for accessible connections.
Creates ~/.fivetran/connector_sdk/options.toml. Migration always writes to this location, even if you specify a different path with --options-file.
Saves the settings in separate profiles named <group_id>-<connection_name>.
Continues with the deployment.

The CLI also generates a commented-out [default] section, for example:

# ["default"]
# python_version = "3.14"
# naming = "FIVETRAN"

The commented-out settings aren't applied automatically. Uncomment the values you want to use, or define your own [default] profile.

Migration is all-or-nothing. If fetching any connection's saved settings fails, it writes no file and logs a warning. The deployment continues using CLI flags and environment variables for that run. Migration retries automatically on the next fivetran deploy run. No manual cleanup is needed.