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 deploy
Deploys your code to Fivetran, creating or updating a connection. If the connection does not exist, it creates one. If the connection with the same name already exists, it prompts you to confirm whether to overwrite it.
Signature
fivetran deploy [OPTIONS]
Parameters
| Flag | Required | Description |
|---|---|---|
--api-key <BASE_64_ENCODED_API_KEY> | Yes | Fivetran API key for deployment. |
--destination <DESTINATION_NAME> | Yes | Destination name in your account. |
--connection <CONNECTION_NAME> | Yes | Connection name in your destination. |
--configuration | Optional | JSON file defining configuration values. |
--non-interactive | Optional | Automatically answers prompts (Yes/No). |
--python <Python version number> , --python-version <Python version number> | Optional | Python runtime version. |
--hybrid-deployment-agent-id <ID> | Optional | If you are using a destination set up for the hybrid deployment model, you can specify a custom hybrid agent (different from that used by the destination) using the CLI parameter --hybrid-deployment-agent-id <ID>. |
--naming | Optional | Naming strategy for the connection schema. FIVETRAN applies standardized transformations (lowercase, replaces special characters with underscores, transliterates non-ASCII). SOURCE preserves original schema, table, and column names with UTF-8 values without modification. See naming conventions for full transformation rules. Only applied when creating a new connection — ignored with a warning if the connection already exists. Defaults to FIVETRAN. Can also be set via the FIVETRAN_NAMING environment variable. |
"<project path>" | Optional | Specifies non-default project path, absolute or relative. When omitted, command runs in current directory. |
Example
fivetran deploy --api-key <API_KEY> --destination Snowflake --connection my_connection
Notes
- When using
fivetran deploy, ensure that your code is structured accordingly and all dependencies are listed inrequirements.txtorpyproject.toml. We don't considerconfiguration.jsonfile as part of the code upload. - Missing required parameters trigger prompts to provide them. Omitting configuration also triggers a confirmation prompt.
- Defaults can be set via environment variables.
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
| Flag | Required | Description |
|---|---|---|
"<project path>" | Optional | Specifies non-default project path, absolute or relative. When omitted, command runs in current directory. |
--non-interactive | Optional | Skip requirements.txt / pyproject.toml validation. |
Example
fivetran package
fivetran package "/Users/fivetran/connector_sdk/my_connector"
fivetran package --non-interactive
Output
Creates a ZIP file at <project_path>/files/<project_name>.zip containing:
- All files except
configuration.json.
Notes
The fivetran package command does the following when creating a package:
- Validates
requirements.txtorpyproject.tomlby default (use--non-interactiveto skip). - Respects
.gitignorepatterns. - Saves the created package in the
files/subdirectory within your project.
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.
Signature
fivetran debug [OPTIONS]
Parameters
| Flag | Required | Description |
|---|---|---|
--configuration | Optional | Specifies the path to a configuration.json file. |
--state | Optional | Specifies the path to a state.json file whose contents will be used as the starting state for the local/debug run. If not provided, we first check for files/state.json and use it if present; otherwise, an empty {} state is created and used. |
--naming | Optional | Naming strategy for the local tester. FIVETRAN applies standardized transformations (lowercase, replaces special characters with underscores, transliterates non-ASCII). SOURCE preserves original schema, table, and column names with UTF-8 values without modification. See naming conventions for full transformation rules. If a warehouse.db already exists with a different strategy, the stored strategy is preserved and this flag is ignored with a warning. Defaults to FIVETRAN. Can also be set via the FIVETRAN_NAMING environment variable. |
"<project path>" | Optional | Specifies a non-default project path, absolute or relative. When omitted, the command runs in the current directory. |
Example
fivetran debug "/Users/fivetran/connector_sdk/sample_connector"
Notes
- The
warehouse.dbfile persists between runs. Usefivetran resetto clear it and start a fresh sync from scratch. - The
--namingstrategy is locked to the value used whenwarehouse.dbwas first created. Passing a different--namingon a subsequent run is ignored with a warning, and the stored strategy is used for the session. - Defaults can be set via environment variables.
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
| Flag | Required | Description |
|---|---|---|
"<project path>" | Optional | Specify non-default project path, absolute or relative. When omitted, command runs in current directory |
Example
fivetran reset
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
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
| Flag | Required | Description |
|---|---|---|
"<project path>" | Optional | Specifies the project path, absolute or relative. If not provided, the command runs in the current directory. If the directory does not exist, it will be created. |
--template <repository path> | Optional | Specifies the template to initialize from. See Template routing for how paths resolve to source repositories. If you don't provide it, the default template connector is used - a fully functional example that runs immediately with fivetran debug without any modifications. |
--non-interactive | Optional | Forces project creation even when connector.py already exists, skips the creation confirmation prompt, and overwrites any existing files without per-file confirmation. |
Template routing
The --template path prefix determines which GitHub repository the files are downloaded from:
| Path prefix | Source repository | Notes |
|---|---|---|
connectors/<name> | fivetran/community_connectors | Community connectors. Recommended when a connector matching your use case exists. |
examples/<path> | fivetran/fivetran_connector_sdk | Quickstart and pattern examples from the SDK repository. |
no --template flag (default) | fivetran/community_connectors | Uses the _template_connector directory as the starting point. |
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 manually or skip this step, choose Skip at the prompt or visit https://github.com/fivetran/connector_sdk_tools.
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 connectors/stripe
# Initialize from a quickstart example
fivetran init --template examples/quickstart_examples/hello
# Initialize in a specific directory from an example, overwriting any existing files
fivetran init ./my-new-connector-project --template examples/quickstart_examples/hello --non-interactive