Setting up the Cognite Toolkit locally

Use this procedure for local CDF development. For production governance, see CI/CD pipeline. Before you start, make sure you have the following prerequisites:

Python v3.10 or later.
Your identity provider details (how you sign in to CDF with your organization account).
Recommended: The Git CLI and basic knowledge of Git.
Recommended: The uv package manager.

Starting a new project

Create a local working folder

This folder holds configuration for all CDF projects in your organization (typically dev, test, and prod). Your organization name appears in the CDF URL: https://<organization>.fusion.cognite.com.

mkdir <your-organization-folder>

Install the Cognite Toolkit

If you manage multiple organizations with different Cognite Toolkit versions, install uv and run the Cognite Toolkit per folder with uv run. Otherwise, install globally with pip:

pip install cognite-toolkit
cdf --version

cd <your-organization-folder>
uv init
uv add cognite-toolkit
uv run cdf --version

This adds a pyproject.toml you can check in to Git to track dependencies.

If the installation fails, see the troubleshooting section.

Run cdf init

Run cdf init and use the arrow keys to work through the setup tasks in order. The next three steps continue in the same cdf init session:

cdf init
? Select a task: (Use arrow keys)
» ○ Create toml file (required)
  ○ Authentication
  ○ Modules
  ○ Git Repository
  > Quit

Create the cdf.toml file

? Select a task: ○ Create toml file (required)
Enter an optional subdirectory for Toolkit content.
    HINT Use an organization directory if you use the 
         repository for more than Toolkit.
    The current directory is the default.
    ?
cdf.toml configuration file initialized in .
✓ Create toml file completed successfully

Press enter to use the current directory. If the repository will hold more than the Cognite Toolkit configuration, enter a subdirectory name instead. The cdf.toml file controls the CLI version and optional features.

Set up credentials

? Select a task: ○ Authentication

Enter the requested authentication values. Choose device code (recommended) or interactive sign-in for local development — client credentials are better suited for CI/CD.Depending on the chosen sign-in flow, the .env file will contain different values as shown below:

Device code
Interactive
Client credentials
Token

Authenticate as a user via a browser prompt. Requires consent permission in your identity provider.

LOGIN_FLOW=device_code
CDF_CLUSTER=<your-cluster>      # e.g. westeurope-1
CDF_PROJECT=<your-project>
IDP_TENANT_ID=<your-tenant-id>

Similar to device code, but opens a browser window directly instead of showing a code.

LOGIN_FLOW=interactive
CDF_CLUSTER=<your-cluster>
CDF_PROJECT=<your-project>
IDP_CLIENT_ID=<your-client-id>
IDP_TENANT_ID=<your-tenant-id>

Authenticate as a service account. Requires a registered application and client secret in your identity provider.

LOGIN_FLOW=client_credentials
CDF_CLUSTER=<your-cluster>
CDF_PROJECT=<your-project>
IDP_CLIENT_ID=<your-client-id>
IDP_CLIENT_SECRET=<your-client-secret>
IDP_TENANT_ID=<your-tenant-id>  # for Entra ID; use IDP_TOKEN_URL instead for other providers

Use when you already have an OAuth2 token, for example from Postman.

LOGIN_FLOW=token
CDF_CLUSTER=<your-cluster>
CDF_PROJECT=<your-project>
CDF_TOKEN=<your-token>

cdf init also writes derived optional values (IDP_AUTHORITY_URL, IDP_SCOPES, etc.) for Entra ID — you don’t need to set these manually. CDF_URL is optional and only needed for private-link or non-standard cluster URLs.

The .env file contains secrets — never check it into version control. The Cognite Toolkit’s .gitignore excludes it by default.

See Authentication for full details on each flow.

Set up folder structure

? Select a task: ○ Modules

Select Modules to create the folder structure for configuration files and environment variables. You can choose a Deployment Pack to install, or select Empty module to start from scratch.

Make the working directory a Git repository

Initialize a Git repository and add the Cognite Toolkit’s default .gitignore and README.md:

git init .
cdf repo init

Verify the setup

Run cdf about to confirm the installation and see your active configuration:

cdf about is also useful for troubleshooting as your project evolves.

cdf about

Cognite Toolkit version: 0.3.x
Python version: 3.11.x
Platform: Darwin 25.x.x

Configuration file found: ./cdf.toml

Plugins
+--------+------------+--------------------------------------------------------------+
| Plugin |   Status   | Description                                                  |
+--------+------------+--------------------------------------------------------------+
| run    | o disabled | plugin for Run command to execute Python scripts in CDF      |
| dump   | o disabled | plugin for Dump command to retrieve Asset resources from CDF |
| dev    | o disabled | plugin for commands to develop modules in CDF                |
| data   | o disabled | plugin for Data command to manage data in CDF                |
+--------+------------+--------------------------------------------------------------+

Alpha Flags
+----------------------------------+------------+----------------------------------------------------------------------+
| Flag                             |   Status   | Description                                                          |
+----------------------------------+------------+----------------------------------------------------------------------+
| import-cmd                       | o disabled | Enables the import sub application                                   |
| profile                          | o disabled | Enables support for the profile command                              |
| infield                          | o disabled | Enables support for Infield configs                                  |
| migrate                          | o disabled | Enables the migrate command                                          |
| signals                          | o disabled | Enables support for signal resources                                 |
| modules-list-json                | o disabled | Enables JSON output format for the modules list command              |
+----------------------------------+------------+----------------------------------------------------------------------+

Additional Configuration:
  Default environment: dev
  Modules version: 0.0.0
  Configured libraries: 1
    - cognite: https://github.com/cognitedata/library/releases/download/latest/packages.zip

Troubleshooting

Windows: path length error — ERROR: Could not install package due to an OSError: [Errno 2] No such file or directory Deployment Pack module paths can exceed Windows’ 260-character limit depending on your install location. Enable long path support: maximum path length limitation.

​Starting a new project

​Troubleshooting

Starting a new project

Troubleshooting