fivetran-connector-sdk Commands

The following CLI commands are available in the fivetran-connector-sdk PyPI package.

CLI (Command-Line Interface) is a text-based interface that lets you run commands directly in a terminal or console to perform tasks. In the context of Connector SDK, you use the CLI to configure, test, or deploy your custom connectors.

fivetran init

Initializes a new Connector SDK project by setting up the project structure, configuration files, and a connector you can run immediately with fivetran debug. By default, you get a functional example connector to build from. Use the --template option to initialize from a community connector for a more complete starting point aligned to your use case.

After creating the project files, fivetran init automatically detects any installed AI coding agents and offers to install the Fivetran Connector SDK plugin for your chosen agent.

Signature

fivetran init [OPTIONS]

Parameters

Template routing

The --template path prefix determines which GitHub repository the files are downloaded from:

AI coding agent setup

After project files are created, fivetran init checks your PATH for installed AI coding agents. If any of the following are detected, you are prompted to choose which one to install the Fivetran Connector SDK plugin for:

• Claude Code (claude)
• Codex CLI (codex)
• Gemini CLI (gemini)
• GitHub Copilot CLI (copilot)

The plugin provides skills for building, testing, deploying, and evaluating connectors directly from your AI coding agent. If you prefer to install or update the plugin manually, or skip this step, choose Skip at the prompt or visit https://github.com/fivetran/connector_sdk_tools.

For fivetran init, both --non-interactive and --yes skip the optional AI agent setup step.

Note: If you face issues while installing the plugin for Codex, please upgrade to the latest version of Codex CLI.

Example

# Initialize a Connector SDK project in the current directory
fivetran init

# Initialize in a specific directory (which is created if it does not exist)
fivetran init ./my-new-connector-project

# Initialize from a community connector
fivetran init --template docusign

# Initialize from a quickstart example
fivetran init --template examples/quickstart/hello

# Initialize in a specific directory from an example, overwriting any existing files
fivetran init ./my-new-connector-project --template examples/quickstart/hello --yes

fivetran debug

Runs and debugs connector code locally. It tests and troubleshoots the connection's behavior with the source's actual data and generates a local warehouse.db file, a DuckDB representation of the data delivered by the connection to the destination. This process internally emulates Fivetran's core, and runs in the same process as the command.

Signature

fivetran debug [OPTIONS]

Parameters

Example

fivetran debug "/Users/fivetran/connector_sdk/sample_connector"

Notes

• The warehouse.db file persists between runs. Use fivetran reset to clear it and start a fresh sync from scratch.
• The --naming strategy is locked to the value used when warehouse.db was first created. Passing a different --naming on a subsequent run is ignored with a warning, and the stored strategy is used for the session.
• Defaults can be set via environment variables.
• If the run fails, the error is shown once, with its traceback, and a crash report is saved in the crash-reports folder of your project.

fivetran run

Runs your connector locally and writes the data to an Apache Iceberg REST catalog that you describe in a destination.json file, instead of the local warehouse.db file. The data goes to your catalog, not to Fivetran. For the format of destination.json, what is written, and what is not supported, see Write to an Iceberg catalog.

Signature

fivetran run [OPTIONS]

Parameters

Example

fivetran run
fivetran run --destination-file ~/catalogs/my_catalog.json "/Users/fivetran/connector_sdk/sample_connector"

Notes

• Use a namespace that is used only for your connector. fivetran run does not ask for confirmation and changes any table with the same name that is already in the namespace.
• On the first run, DuckDB downloads its Iceberg extension, so the machine needs internet access.

fivetran configuration

Interactively collects configuration values from setup form fields and writes them to configuration.json. Use --test to run setup tests registered with ConfigurationForm.add_test().

Signature

fivetran configuration [OPTIONS]

Parameters

Example

fivetran configuration
fivetran configuration --test
fivetran configuration --non-interactive
fivetran configuration --yes

Notes

• Requires a connector that defines a setup form using the configuration_form method. If the connector does not define one, this command exits without generating configuration.json.
• fivetran configuration writes configuration.json to the project directory (current directory by default). If a configuration.json already exists there, it overwrites the file only after confirmation. Use --yes to overwrite without confirmation.
• fivetran configuration --test requires an existing configuration.json.

fivetran reset

Deletes the current local state.json and warehouse.db file. It allows to re-run fivetran debug from scratch. This simulates the initial sync as the connector behaves as if it is running for the first time.

Signature

fivetran reset [OPTIONS]

Parameters

Example

fivetran reset

fivetran deploy

Deploys your Connector SDK code to Fivetran, creating or updating a connection. If a connection with the specified name already exists in the destination, the CLI prompts you to confirm whether to overwrite it.

fivetran deploy takes deployment options, which configure where and how your connector is deployed. You can pass these options explicitly through the supported CLI flags. Alternatively, you can set them through environment variables. Starting with fivetran-connector-sdk v3.0.0, you can also store select deployment options in a local deployment options file. The following table outlines all supported deployment options and the various ways of configuring them.

Signature

fivetran deploy [OPTIONS]

Deployment options

Field resolution order

For each deployment option, the CLI takes the first value it finds, in this order:

1. CLI flag
2. Environment variable
3. Deployment options file, using the selected profile
4. SDK built-in default; if none exists and the option is required, the deploy fails with a clear error

Examples

Deploy using CLI flags

fivetran deploy --api-key <API_KEY> --destination Snowflake --connection my_connection

# Deploy with a Proxy Agent and a custom host key
fivetran deploy --api-key <API_KEY> --destination Snowflake --connection my_connection \
  --proxy-id <PROXY_AGENT_ID> --proxy-host-config-key db_endpoint

Deploy using environment variables

export FIVETRAN_API_KEY=<API_KEY>
export FIVETRAN_DESTINATION_NAME=Snowflake
export FIVETRAN_CONNECTION_NAME=my_connection
fivetran deploy

Deploy using a deployment options file profile

The following examples show the different ways to select the deployment options file and profile.

Specify both the options file and the profile

fivetran deploy --api-key <API_KEY> --options-file ./config/options.toml --profile development

Use the default deployment options file location and specify a profile

The CLI looks for options.toml in the current directory, then in ~/.fivetran/connector_sdk/. See File discovery.

fivetran deploy --api-key <API_KEY> --profile development

Specify neither the options file nor the profile

The CLI uses the deployment options file from the default location and the [default] profile, if it exists.

fivetran deploy --api-key <API_KEY>

Redeploy without confirmation

Use --yes to skip the overwrite confirmation prompt. This example assumes you set FIVETRAN_API_KEY and provide the Python version through FIVETRAN_PYTHON_VERSION or the selected options-file profile. For an existing connection in a Hybrid Deployment destination, also provide the agent ID through FIVETRAN_HD_AGENT_ID or that profile:

fivetran deploy --destination Snowflake --connection my_connection --python-version 3.14 --yes

Command output

Every deploy logs the resolved value and source for each managed field:

reading options from /home/user/.fivetran/connector_sdk/options.toml
resolved options:
  destination = Testing (provided via --destination)
  connection = my_connection (provided via --connection)
  python_version = 3.11 (provided via options file, profile [group_id_a-connection_a])
  naming = FIVETRAN_NAMING (using SDK built-in default)
  proxy_id = proxy-1 (provided via options file, profile [group_id_a-connection_a])

If a required field cannot be resolved, deployment fails before anything is created or updated and all missing fields are reported together:

--destination is required; provide it via the --destination flag, the FIVETRAN_DESTINATION_NAME environment variable, or the options file (profile [default])
--connection is required; provide it via the --connection flag, the FIVETRAN_CONNECTION_NAME environment variable, or the options file (profile [default])

Notes

• When using fivetran deploy, ensure that your code is structured accordingly and all dependencies are listed in requirements.txt or pyproject.toml. We don't consider the configuration.json and destination.json file as part of the code upload.
• --non-interactive uses the default answer for each y/n prompt (indicated by capital letter, e.g., y/N defaults to No). It does not supply missing required values.
• --yes always answers Yes to y/n prompts.

fivetran package

Creates a local ZIP package of your connector code without deploying it to Fivetran. Once you have created the package, you can upload it to Fivetran using the Connector SDK Package Management API. This is useful for REST API deployment workflows, version control, archiving your code, or manual inspection of package contents before deployment.

Signature

fivetran package [OPTIONS]

Parameters

Example

fivetran package
fivetran package "/Users/fivetran/connector_sdk/my_connector"
fivetran package --non-interactive
fivetran package --yes

Output

Creates a ZIP file at <project_path>/files/<project_name>.zip containing:

• All files except configuration.json and destination.json.

Notes

The fivetran package command does the following when creating a package:

• Validates requirements.txt or pyproject.toml by default (use --non-interactive or --yes to skip).
• Respects .gitignore patterns.
• Saves the created package in the files/ subdirectory within your project.

fivetran version

Displays installed SDK version. Version is required for getting support from Fivetran and troubleshooting issues.

fivetran version # This format works.
fivetran --version # This format works as well.

fivetran --help

Lists all available commands and parameters.

fivetran --help