You can deploy your Flows custom app to CDF interactively from your machine (browser sign-in, no OAuth secrets in the terminal) or automate deployment in CI/CD with client credentials.
Interactive deployment
The simplest path uses your browser for sign-in—no OAuth configuration in the terminal:
npx @cognite/cli@latest apps deploy --interactive
- Build your app.
- Open a browser window for you to sign in to CDF.
- Prompt you to select a deployment target from
app.json.
- Package and deploy to your configured project.
- Show a link to your deployed app.
Options
# Use the first deployment target (skip selection prompt)
npx @cognite/cli@latest apps deploy --interactive -d 0
# Use a specific project by name
npx @cognite/cli@latest apps deploy --interactive -d your-project-name
# Skip the build step (if already built)
npx @cognite/cli@latest apps deploy --interactive --skip-build
Draft and published versions
apps deploy uploads your app as a Draft version. To publish and activate it, see App lifecycle.
--published flag is used for legacy apps:| Scenario | Behavior |
|---|
Legacy app, --published flag | Honored — deploys as published |
App Hosting app, --published flag | Warning printed, flag ignored — always deploys as DRAFT. Use apps publish . / apps activate . instead |
npx @cognite/cli@latest apps publish . and npx @cognite/cli@latest apps activate . to control visibility.App Hosting lifecycle commands
For apps using App Hosting infrastructure ("infra": "appsApi" in app.json), use the following commands to manage the version lifecycle after deployment. Each version progresses through the states: DRAFT → PUBLISHED → ACTIVE.
Check status
Print the current deployment status of your app version:
npx @cognite/cli@latest apps status .
Publish a version
Transition the current version from DRAFT to PUBLISHED (visible but not yet the active version):
npx @cognite/cli@latest apps publish .
Activate a version
Set the current version as ACTIVE (the version users see). Publish the version if it’s still DRAFT:
npx @cognite/cli@latest apps activate .
Use --interactive to authenticate via browser sign-in when running these commands from your machine:npx @cognite/cli@latest apps status . --interactive
npx @cognite/cli@latest apps publish . --interactive
npx @cognite/cli@latest apps activate . --interactive
Automated deployment (CI/CD)
For CI/CD pipelines, configure client credentials.
Prerequisites
- OAuth client — A client ID registered in your CDF project.
- Client secret — The secret for that client.
- Capabilities — The
apphosting:read and apphosting:write capabilities granted to the client via a group. These capabilities can be scoped to the app’s externalId from app.json. Add apphosting:run if the same client also needs to run the app. See Assign capabilities.
Ask your Cognite administrator to register an OAuth client with the required permissions.
Add deployClientId and deploySecretName to your deployment configuration:
{
"name": "My App",
"description": "My awesome Flows app",
"externalId": "my-app",
"versionTag": "1.0.0",
"deployments": [
{
"org": "my-org",
"project": "my-project",
"baseUrl": "https://api.cognitedata.com",
"deployClientId": "your-client-id",
"deploySecretName": "MY_APP_SECRET"
}
]
}
| Field | Description |
|---|
name | Display name in CDF |
externalId | Unique identifier (kebab-case) |
versionTag | Semantic version |
deployClientId | OAuth client ID |
deploySecretName | Environment variable name for the secret |
idpType | Identity provider (cdf or entra_id). Defaults to cdf |
tenantId | Microsoft Entra tenant ID (required when idpType is entra_id) |
published | Legacy field: whether the app is visible to end users. Prefer apps publish / apps activate for App Hosting apps. |
Microsoft Entra ID deployment
Set idpType to entra_id and provide tenantId:
{
"deployments": [
{
"org": "my-org",
"project": "my-project",
"baseUrl": "https://api.cognitedata.com",
"deployClientId": "your-entra-client-id",
"deploySecretName": "MY_APP_SECRET",
"idpType": "entra_id",
"tenantId": "00000000-0000-0000-0000-000000000000"
}
]
}
idpType is entra_id, Flows requests a token from Microsoft Entra ID and derives the CDF scope from baseUrl (for example, https://greenfield.cognitedata.com/.default).
Step 2: Set the secret
Export the client secret:
export MY_APP_SECRET="your-client-secret"
In CI/CD, store secrets in your platform’s secret manager (for example, GitHub Actions repository secrets, Azure DevOps variable groups, or GitLab CI variables).
Step 3: Deploy
This will:
- Build your app (
tsc && vite build).
- Package
dist/ into a zip.
- Authenticate with client credentials.
- Upload through the CDF Files API.
- Make the app available in CDF.
Preview deployments
For pull request previews:
Multiple environments
Add multiple entries to deployments:
{
"deployments": [
{
"org": "your-org",
"project": "dev-project",
"baseUrl": "https://api.cognitedata.com",
"deployClientId": "dev-client-id",
"deploySecretName": "DEV_SECRET"
},
{
"org": "your-org",
"project": "prod-project",
"baseUrl": "https://api.cognitedata.com",
"deployClientId": "prod-client-id",
"deploySecretName": "PROD_SECRET"
}
]
}
Versioning
Update versionTag in app.json for each release:
{
"versionTag": "1.2.0"
}
Troubleshooting
What permissions do I need to deploy?
Your OAuth client (for CI/CD) or user account (for interactive deployment) needs apphosting:read and apphosting:write. You can scope these capabilities to the app’s externalId from app.json. Add apphosting:run if the same principal also needs to run the app. See Assign capabilities.
”Deployment secret not found”
Ensure the environment variable name matches deploySecretName:
export MY_APP_SECRET="your-secret"
“Failed to authenticate”
Check that:
- The client ID is correct.
- The client secret is valid and not expired.
- The client has the required CDF permissions (including Files API write access).
Build fails
Run the build locally:
Interactive sign-in issues
- Confirm you have access to the CDF project.
- Ensure pop-ups are not blocked.
- Try
npx @cognite/cli@latest apps deploy --interactive --org your-org as a hint.
Further reading
