Skip to main content
With the Cognite Toolkit, you first configure access to the CDF project(s) you’ll administer. Next, you define and configure the modules you want to build and deploy. Then, you run the cdf build command to build the necessary artifacts to deploy the modules. Before you deploy the artifacts, we recommend that you always do a dry-run deployment to verify that the configurations and deployment perform as expected. When you’ve verified the configuration, you run the cdf deploy command to deploy the artifacts to the CDF project using the CDF SDK and APIs.

​
Before you start

Complete these prerequisites before you build and deploy:
  • Install the Cognite Toolkit and open a terminal in your project directory.
  • Set up authentication with cdf auth init and cdf auth verify so the Toolkit can access the target CDF project.
  • Initialize modules with cdf modules init (or use an existing project that already has a modules/ directory and config.<env>.yaml files).
1

Configure access to the CDF project

Confirm that authentication works for the CDF project you plan to deploy to. If you have not configured credentials yet, follow Authentication, run cdf auth init, and verify access with cdf auth verify.
2

Configure modules

To configure the modules to deploy to a CDF project:
  1. The cdf modules init command will usually have created a config.<env>.yaml file for each of your environments.
    You need one config.<env>.yaml file for each CDF project you deploy to. For example, if you have prod, staging, and dev projects/environments, you need config.prod.yaml, config.staging.yaml, and config.dev.yaml configuration files.
  2. Open the configuration file, and edit the project property to match the name of your CDF project (line 3 in this example):
    showLineNumbers
  3. In the selected property, list the modules you want to deploy (lines 6-7 above). You can list any of the modules in the modules sub-directory.
  4. Update the variables in the variables section to match the CDF project you’re deploying to, for example, to change the name of your default location.
    Make sure that you update all the variables that are set to <change_me>. If not, the module won’t be deployed correctly.
  1. Save the configuration file.
3

Build deployment artifacts

To build the artifacts to deploy for the modules you have configured:
  1. In a terminal, run these commands:
    The --config-yaml=<env> parameter specifies which configuration file to use, in this example config.dev.yaml.
The Cognite Toolkit substitutes the variables in the templates and creates a build/ output directory with the artifacts to deploy.During the build, the Toolkit produces insights that help you create good configurations. Insights include recommendations for best practices, syntax warnings, and consistency checks. If Neat is installed, the build also validates your data models and reports any issues.
4

Deploy to the CDF project

To deploy the configured artifacts to your CDF project:
  1. In a terminal, run these commands to do a dry-run of the deployment:
  2. Inspect the output from the dry run and verify that the configurations and deployment perform as expected.
    Output from --dry-run command
  3. Run this command to deploy the artifacts to your CDF project:
To ensure that history and logs are not overwritten, the Cognite Toolkit deploys only configurations that have changed since the last run, and updates the configurations in the CDF project.
From v0.8, the cdf deploy command sends all content from YAML files to CDF, including parameters the Toolkit doesn’t explicitly know about. This ensures forward compatibility with new CDF API fields without waiting for a Toolkit update.
5

Clean up configurations and data (optional)

To deploy from a clean state, you can remove configurations and data before you deploy. This is typically not necessary for regular deployments, but can be useful when a resource rejects updates and you want to force a clean deployment.One use case is data modeling views. Views can reject an update when the change requires a version bump. To delete and recreate the view (common in development), use the --drop option before deploying again.
Use these commands with caution so you do not accidentally delete configurations and data. Always run commands with --dry-run first to inspect the potential impact.
Remove and redeploy configurations (keep data)
Remove and redeploy configurations and data
Delete everything managed by your configurations
Last modified on July 6, 2026