Cognite CLI command reference

This page is the command reference for @cognite/cli@latest, the Cognite CLI for Flows custom apps in Cognite Data Fusion (CDF). All commands are available with npx @cognite/cli@latest <command>, or with cognite <command> when the CLI is installed globally. This page documents the apps, agents, and keys command groups. For a walkthrough from scaffold to activation, see Quickstart: Deploy Flows custom apps with the Cognite CLI. For a walkthrough from scaffold to activation for Atlas AI agents, see Building Atlas AI agents with the Cognite CLI.

cognite [options] [command]

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  apps            Manage Flows custom apps — create, deploy, and manage version lifecycle
  agents          Manage Atlas AI agents — create, iterate, evaluate, and publish
  keys            Manage code signing keys

`apps`

Manage the full lifecycle of Flows custom apps.

npx @cognite/cli@latest apps <subcommand> [options]

`apps create`

Scaffold a new Flows custom app.

npx @cognite/cli@latest apps create [directory] [options]

Argument / Option	Description
`[directory]`	Target directory (`.` for current, or a subdirectory name).
`--display-name <name>`	App display name (skips the prompt).
`--description <description>`	App description (skips the prompt).
`--org <org>`	Deployment organization (skips the prompt).
`--project <project>`	Deployment project (skips the prompt).
`--cluster <cluster>`	CDF cluster, for example, `greenfield` (skips the prompt).
`--base-url <url>`	CDF base URL, for example, `https://greenfield.cognitedata.com` (skips the prompt; defaults to a cluster-derived URL when omitted).
`--spec-kit`	Install spec-kit slash commands (skips the prompt).
`--no-spec-kit`	Skip spec-kit installation (skips the prompt).

The following examples show typical apps create invocations.

# Interactive
npx @cognite/cli@latest apps create

# Target subdirectory
npx @cognite/cli@latest apps create my-app

# Fully non-interactive (CI/AI agents)
npx @cognite/cli@latest apps create my-app \
  --display-name "My App" \
  --description "My app" \
  --org cog-atlas \
  --project atlas-greenfield \
  --cluster greenfield \
  --base-url https://greenfield.cognitedata.com

`apps deploy`

Build and deploy your app to CDF.

npx @cognite/cli@latest apps deploy [options]

Option	Description
`-d, --deployment <target>`	Deployment target — index (for example, `0`, `1`) or project name from `app.json`.
`--skip-build`	Skip the build step.
`--interactive`	Use browser-based OpenID Connect (OIDC) authentication instead of credentials from environment variables.
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive`).

For non-interactive deploy, set deployClientId and deploySecretName per deployment in app.json. deploySecretName is the name of the environment variable that holds the client secret. Set that variable before you deploy:

MY_CLIENT_SECRET=<your-secret> npx @cognite/cli@latest apps deploy

The following examples show typical apps deploy invocations.

npx @cognite/cli@latest apps deploy                      # First deployment target, environment-variable authentication
npx @cognite/cli@latest apps deploy -d 1                 # Second deployment target
npx @cognite/cli@latest apps deploy -d my-project        # Deploy to project by name
npx @cognite/cli@latest apps deploy --skip-build         # Deploy without rebuilding
npx @cognite/cli@latest apps deploy --interactive        # Browser authentication, prompts for target
npx @cognite/cli@latest apps deploy --interactive -d 0   # Browser authentication, target chosen non-interactively

`apps status`

Show the deployment status and signatures of the current app version.

npx @cognite/cli@latest apps status [path] [options]

Argument / Option	Description
`[path]`	Path to the app folder (default: `.`). Only `.` is supported.
`-d, --deployment <target>`	Deployment target from `app.json` (index or name).
`--interactive`	Browser-based authentication.
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive`).

The following examples show typical apps status invocations.

npx @cognite/cli@latest apps status .                     # Status using environment-variable authentication
npx @cognite/cli@latest apps status . --interactive       # Status using browser authentication

`apps metadata`

Manage the deployed app’s metadata (display name and description).

npx @cognite/cli@latest apps metadata <subcommand> [options]

`apps metadata update`

Push displayName and description from app.json to the already-deployed app record in CDF.

npx @cognite/cli@latest apps metadata update [path] [options]

Argument / Option	Description
`[path]`	Path to the app folder (default: `.`). Only `.` is supported.
`-d, --deployment <target>`	Deployment target from `app.json` (index or name).
`--interactive`	Browser-based authentication.
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive`).

The following examples show typical apps metadata update invocations.

npx @cognite/cli@latest apps metadata update .                    # Update metadata using environment-variable authentication
npx @cognite/cli@latest apps metadata update . --interactive      # Update metadata using browser authentication

`apps publish`

Transition the current app version from DRAFT to PUBLISHED. For the version state model, see About the Flows custom app lifecycle.

npx @cognite/cli@latest apps publish [path] [options]

Argument / Option	Description
`[path]`	Path to the app folder (default: `.`).
`-d, --deployment <target>`	Deployment target from `app.json`.
`--interactive`	Browser-based authentication.
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive`).

The following examples show typical apps publish invocations.

npx @cognite/cli@latest apps publish .                    # Publish using environment-variable authentication
npx @cognite/cli@latest apps publish . --interactive      # Publish using browser authentication

`apps activate`

Activate the current app version. The command publishes the version if needed, then sets the ACTIVE alias so users see this version.

npx @cognite/cli@latest apps activate [path] [options]

Argument / Option	Description
`[path]`	Path to the app folder (default: `.`).
`-d, --deployment <target>`	Deployment target from `app.json`.
`--interactive`	Browser-based authentication.
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive`).

The following examples show typical apps activate invocations.

npx @cognite/cli@latest apps activate .                   # Activate using environment-variable authentication
npx @cognite/cli@latest apps activate . --interactive     # Activate using browser authentication

`apps deactivate`

Deactivate the app by removing the ACTIVE alias so users no longer see this version.

npx @cognite/cli@latest apps deactivate [path] [options]

Argument / Option	Description
`[path]`	Path to the app folder (default: `.`).
`-d, --deployment <target>`	Deployment target from `app.json`.
`--interactive`	Browser-based authentication.
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive`).

The following examples show typical apps deactivate invocations.

npx @cognite/cli@latest apps deactivate .                 # Deactivate using environment-variable authentication
npx @cognite/cli@latest apps deactivate . --interactive   # Deactivate using browser authentication

`apps delete`

Delete the current app version from CDF.

Use apps deactivate first if the version is ACTIVE since apps delete is destructive.

npx @cognite/cli@latest apps delete [path] [options]

Argument / Option	Description
`[path]`	Path to the app folder (default: `.`). Only `.` is supported.
`-d, --deployment <target>`	Deployment target from `app.json` (index or name).
`--interactive`	Browser-based authentication.
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive`).
`-f, --force`	Skip the confirmation prompt.

The following examples show typical apps delete invocations.

npx @cognite/cli@latest apps delete .                     # Delete using environment-variable authentication
npx @cognite/cli@latest apps delete . --interactive       # Delete using browser authentication
npx @cognite/cli@latest apps delete . --force             # Skip confirmation prompt

`apps setup-https`

Generate trusted local HTTPS certificates using mkcert. Required for local development when your app expects an HTTPS origin. For install and browser-trust steps, see Trusting the local HTTPS certificate for Flows custom apps.

npx @cognite/cli@latest apps setup-https [options]

Option	Description
`--cert-dir <path>`	Directory to write certificates into (default: `./certificates/mkcert`).

The following examples show typical apps setup-https invocations.

npx @cognite/cli@latest apps setup-https                         # Write certs to ./certificates/mkcert
npx @cognite/cli@latest apps setup-https --cert-dir ./certs      # Custom output directory

`apps submit`

Package the app source and open a pre-filled Zendesk form for app certification submission. For the full certification workflow, see Certifying a Flows custom app for production.

npx @cognite/cli@latest apps submit

This command does the following:

Packages the app source into a zip archive.
Opens your browser to the Cognite certification Zendesk form.
Opens your file manager to the generated package so you can attach it.

The following example shows a typical apps submit invocation.

npx @cognite/cli@latest apps submit

`apps sign`

Sign an app bundle for Cognite certification. The default bundle path is .cognite-bundles/<app>-<version>.zip. For the signing workflow, see Signing Flows custom apps from the CLI.

npx @cognite/cli@latest apps sign [bundle] [options]

Argument / Option	Description
`[bundle]`	Path to the bundle to sign (default: `.cognite-bundles/<app>-<version>.zip`).
`--key <path>`	Private key PEM file path.
`-s, --signing-identity <kid>`	Key ID for Keychain or file-based key lookup.
`--appid <id>`	Application ID (default: `externalId` from `app.json`).
`-i, --identifier <id>`	Alias for `--appid`.
`--app-version <version>`	App version (default: `versionTag` from `app.json`).
`--scope <org/project...>`	Deployment scope(s) (default: deployments from `app.json`).
`-r, --requirements <org/project...>`	Alias for `--scope`.
`-o, --output <path>`	Output signature file path (default: `<bundle>.<dev\|cert>.sig`).
`-v, --verbose`	Display full payload after signing.
`--as-certifier`	Counter-sign a developer signature as certifier.
`--interactive`	Enable interactive prompts (key selection, passphrase, deployment target).
`--browser-auth`	Use browser-based Proof Key for Code Exchange (PKCE) authentication when submitting the signature.
`-d, --deployment <target>`	Deployment target from `app.json` (submit step only).
`--base-url <url>`	CDF base URL (only with `--interactive`).
`--project <project>`	CDF project name (only with `--interactive`).
`--org <org>`	Organization hint for sign-in (only with `--interactive` or `--browser-auth`).

`apps skills`

Manage AI agent skills for your app. Compatible agents include Claude Code and Cursor. See About builder skills.

npx @cognite/cli@latest apps skills <subcommand> [options]

`apps skills pull`

Pull skills into your project.

npx @cognite/cli@latest apps skills pull [options]

Option	Description
`--skill <name>`	Pull a specific skill by name (for example, `create-client-tool`).

`apps skills list`

List the skills installed in your project.

npx @cognite/cli@latest apps skills list

The following examples show typical apps skills invocations.

npx @cognite/cli@latest apps skills pull                               # Pull all skills
npx @cognite/cli@latest apps skills pull --skill create-client-tool   # Pull a specific skill
npx @cognite/cli@latest apps skills list                              # List installed skills

`agents`

Manage Atlas AI agents from a local project (<name>.agent.yaml + eval/eval.yaml). Requires @cognite/cli 1.10.0 or later.

npx @cognite/cli@latest agents <subcommand> [options]

Most agents subcommands accept shared auth options:

Option	Description
`--interactive`	Use browser-based authentication.
`--base-url <url>`	CDF base URL (with `--interactive`).
`--project <name>`	CDF project (with `--interactive`).
`--org <org>`	Organization hint for login (with `--interactive`).

Prefer a persisted session when available: npx @cognite/cli@latest auth login. See also: Agent definition (<name>.agent.yaml), Agent evaluation cases, Building Atlas AI agents with the Cognite CLI.

`agents create`

Scaffold a new agent project.

npx @cognite/cli@latest agents create [directory] [options]

Argument / Option	Description
`[directory]`	Agent name / target directory.
`--external-id <id>`	Agent `externalId`.
`--display-name <name>`	Agent display name.
`--description <text>`	Agent description.
`--model <model>`	Language model (for example `azure/gpt-4.1`).
`--instructions <text>`	Agent instructions (custom behavior; platform guidance still applies).
`--runtime-version <version>`	Agent runtime version.
`--no-prompt`	Skip interactive prompts; use defaults / flags.

npx @cognite/cli@latest agents create my-agent --no-prompt \
  --external-id my-agent \
  --display-name "My Agent"

`agents push`

Push a draft agent from the local <name>.agent.yaml to CDF.

npx @cognite/cli@latest agents push [directory]

Argument	Description
`[directory]`	Agent project directory.

`agents pull`

Pull a deployed agent by externalId into <folderName>.agent.yaml in the target directory (default: current directory). The filename follows the folder, not the externalId.

npx @cognite/cli@latest agents pull <external-id> [directory] [options]

Argument / Option	Description
`<external-id>`	`externalId` of the agent to pull.
`[directory]`	Agent project directory (default: `.`).
`--force`	Overwrite the existing agent definition without prompting.

npx @cognite/cli@latest agents pull my-agent
npx @cognite/cli@latest agents pull my-agent ./my-agent
npx @cognite/cli@latest agents push ./my-agent

`agents open`

Open the agent in the Atlas AI Agent builder. Optional --upsert pushes first.

npx @cognite/cli@latest agents open [directory] [options]

Argument / Option	Description
`[directory]`	Agent project directory.
`--upsert`	Push the local `<name>.agent.yaml` before opening.

`agents publish`

Publish the agent (adds production visibility, for example the published label) and push.

npx @cognite/cli@latest agents publish [directory]

`agents unpublish`

Remove production visibility and push.

npx @cognite/cli@latest agents unpublish [directory]

`agents list`

List agents in the project.

npx @cognite/cli@latest agents list [options]

Option	Description
`--json`	Emit machine-readable JSON.

`agents status`

Show local vs remote agent status.

npx @cognite/cli@latest agents status [directory] [options]

Argument / Option	Description
`[directory]`	Agent project directory.
`--external-id <id>`	Status for this external ID.
`--json`	Emit machine-readable JSON.

`agents eval`

Run eval/eval.yaml against a deployed agent and score responses.

npx @cognite/cli@latest agents eval [directory] [options]

Argument / Option	Description
`[directory]`	Agent project directory (must contain `eval/eval.yaml`).
`--case <id>`	Run only this case id (repeatable).
`--tag <tag>`	Run only cases with this tag (repeatable).
`--judge-model <model>`	LLM model for scoring (for example `azure/gpt-5`).
`--external-id <id>`	Evaluate this deployed agent (skips local `<name>.agent.yaml`).
`--system-agent`	Evaluate the Cognite system agent (mutually exclusive with `--external-id`).
`--upsert`	Push local `<name>.agent.yaml` before evaluation (not with `--external-id` / `--system-agent`).
`--fail-fast`	Stop after the first failing case.
`-v, --verbose`	Log request/response traces to stderr.
`--fail-on-tool-confirmation`	Fail instead of auto-approving tool confirmation prompts.
`--report-dir [path]`	Write `report.json` + `report.md` (default directory `eval-report`).

npx @cognite/cli@latest agents eval --upsert
npx @cognite/cli@latest agents eval --case greeting -v
npx @cognite/cli@latest agents eval --tag ci --report-dir

Schema and scorers: Agent evaluation cases.

`keys`

Manage Ed25519 code signing keys used to sign app bundles.

npx @cognite/cli@latest keys <subcommand> [options]

`keys generate`

Generate a new Ed25519 keypair for code signing. On macOS, the private key is stored in the system Keychain by default.

npx @cognite/cli@latest keys generate [options]

Option	Description
`-o, --output <path>`	Write the encrypted private key to this file path (forces file storage even on macOS).
`--no-keychain`	Skip macOS Keychain and write a passphrase-encrypted key to `~/.cognite-cli/keys/` instead.
`-e, --expires <months>`	Validity in months (1-12); skips the interactive prompt.
`--email <address>`	Email address for the key registry entry; skips the interactive prompt.
`--kid <identifier>`	Signing identity name for the registry (for example, `jsmith-dev-001`); skips the interactive prompt.
`--force`	Overwrite an existing key without prompting for confirmation.
`--copy-link`	Copy the Zendesk registration link to the clipboard without prompting.
`--interactive`	Prompt for any required flags that are not supplied.

The following example shows a typical keys generate invocation.

npx @cognite/cli@latest keys generate \
  --email developer@example.com \
  --kid jsmith-dev-001 \
  --expires 12

`keys list`

List all local signing identities and their storage location (Keychain or file).

npx @cognite/cli@latest keys list

Develop

SDKs and toolkits

Cognite CLI command reference

`apps`

`apps create`

`apps deploy`

`apps status`

`apps metadata`

`apps metadata update`

`apps publish`

`apps activate`

`apps deactivate`

`apps delete`

`apps setup-https`

`apps submit`

`apps sign`

`apps skills`

`apps skills pull`

`apps skills list`

`agents`

`agents create`

`agents push`

`agents pull`

`agents open`

`agents publish`

`agents unpublish`

`agents list`

`agents status`

`agents eval`

`keys`

`keys generate`

`keys list`

Further reading

​apps

​apps create

​apps deploy

​apps status

​apps metadata

​apps metadata update

​apps publish

​apps activate

​apps deactivate

​apps delete

​apps setup-https

​apps submit

​apps sign

​apps skills

​apps skills pull

​apps skills list

​agents

​agents create

​agents push

​agents pull

​agents open

​agents publish

​agents unpublish

​agents list

​agents status

​agents eval

​keys

​keys generate

​keys list

​Further reading

`apps`

`apps create`

`apps deploy`

`apps status`

`apps metadata`

`apps metadata update`

`apps publish`

`apps activate`

`apps deactivate`

`apps delete`

`apps setup-https`

`apps submit`

`apps sign`

`apps skills`

`apps skills pull`

`apps skills list`

`agents`

`agents create`

`agents push`

`agents pull`

`agents open`

`agents publish`

`agents unpublish`

`agents list`

`agents status`

`agents eval`

`keys`

`keys generate`

`keys list`

Further reading