Deploy Use Case

When to use

Deploy n8n workflows + config to the Codika platform
After creating or modifying workflow files
After a successful verify use-case check

Prerequisites

codika CLI installed and authenticated
Use case folder with config.ts and workflows/ directory
Platform project (via project.json or PROJECT_ID in config.ts)

Recommended flow

cd my-use-case
codika project create --name "My Project" --path .   # If no project.json
codika verify use-case .                              # Validate first
codika deploy use-case .                              # Deploy

Command

codika deploy use-case <path> [options]

Arguments

Argument	Description
`<path>`	Path to use case folder (must contain `config.ts` and `workflows/`)

Options

Option	Description	Default
`--api-url <url>`	Codika API URL	`CODIKA_API_URL` env or profile
`--api-key <key>`	Codika API key	`CODIKA_API_KEY` env or profile
`--project-id <id>`	Override project ID	`project.json` or `config.ts`
`--project-file <path>`	Path to custom project file (e.g., `project-client-a.json`)	`project.json`
`--patch`	Patch version bump	Default
`--minor`	Minor version bump	—
`--major`	Major version bump	—
`--target-version <X.Y>`	Explicit API version	—
`--additional-file <abs:rel>`	Add extra file (repeatable)	—
`--json`	JSON output	—
`--profile <name>`	Use a specific profile instead of the active one	—
`--dry-run`	Preview without calling API	—

Version strategy

Flag	Local version change	API version strategy
`--patch` (default)	1.0.0 → 1.0.1	`minor_bump`
`--minor`	1.0.1 → 1.1.0	`minor_bump`
`--major`	1.1.0 → 2.0.0	`major_bump`
`--target-version 3.0`	Unchanged	`explicit` (version 3.0)

What happens on deploy

Read version.json for current version
Validate the use case (same as verify use-case)
Bump version based on flags
Resolve project ID: --project-id > --project-file > project.json > config.ts
Resolve API key: --api-key > env > org-matching profile > active profile
Package all workflow files
Send to the Codika platform API
Collect agent skills from skills/*/SKILL.md (if any exist)
On success:
- Update version.json with new local version
- Save devProcessInstanceId to project.json
- Save deployment to deployments map in project.json (version → templateId + timestamp)
- Archive deployment in deployments/{projectId}/process/{apiVersion}/
- Update project-info.json with version mapping

Agent skills are automatically included. If your use case has a skills/ folder with SKILL.md files, they are collected and sent with the deployment. Agents can then download them via codika get skills. No config.ts changes needed.

The deployments map in project.json tracks all deployments by version — use it with codika publish to promote a deployment to production.

For parameter-only changes, use codika rerun deployment instead. It updates deployment parameters on an existing instance without creating a new template version — no version bump, no new deployment archive.

API key resolution (org-aware)

If project.json contains organizationId, the CLI automatically selects the profile matching that org:

--api-key flag (always wins)
CODIKA_API_KEY environment variable
Profile matching organizationId from project.json
Active profile

Dry-run mode

Preview the deployment without calling the API:

codika deploy use-case ./my-use-case --dry-run

This validates the configuration, displays the deployment plan (versions, workflows, project ID, integrations), and exits with the validation status.

Additional files

Attach extra files to the deployment (e.g., documentation, data files):

codika deploy use-case ./my-use-case \
  --additional-file "/absolute/path/to/readme.md:docs/readme.md" \
  --additional-file "/absolute/path/to/data.json:data/seed.json"

Format: absolutePath:relativePath — the relative path determines where the file is stored in the deployment archive.

Post-deploy files

After a successful deployment, the folder contains:

my-use-case/
  version.json              # Updated with new version
  project.json              # Updated with devProcessInstanceId + deployments map
  data-ingestion/           # Optional — process-level DI (deployed separately)
    embedding.json
  deployments/
    {projectId}/
      project-info.json     # Version mapping history
      process/
        {apiVersion}/
          deployment-info.json
          config-snapshot.json
          workflows/*.json
      data-ingestion/       # Present if DI was deployed
        {apiVersion}/
          deployment-info.json
          config-snapshot.json
          <workflow>.json

Data ingestion workflows live in a separate data-ingestion/ folder and are deployed independently via codika deploy process-data-ingestion. They have their own version line and do not trigger “update available” notifications.

Examples

# Default deployment (patch bump)
codika deploy use-case ./email-automation

# Minor version bump
codika deploy use-case ./email-automation --minor

# Major version bump
codika deploy use-case ./email-automation --major

# Explicit API version
codika deploy use-case ./email-automation --target-version 2.0

# Dry-run preview
codika deploy use-case ./email-automation --dry-run

# Deploy with specific project ID
codika deploy use-case ./email-automation --project-id abc123

# JSON output for CI
codika deploy use-case ./email-automation --json

# With extra documentation file
codika deploy use-case ./email-automation \
  --additional-file "/path/to/readme.md:docs/readme.md"

Output

✓ Deployed successfully
  Version:     1.2.4 (API: 1.3)
  Workflows:   3
  Project:     abc123
  Instance:    def456

Exit codes

Code	Meaning
`0`	Deployment successful
`1`	API error or validation failure

Overview

Setup

Build

Deploy

Operate

When to use

Prerequisites

Recommended flow

Command

Arguments

Options

Version strategy

What happens on deploy

API key resolution (org-aware)

Dry-run mode

Additional files

Post-deploy files

Examples

Output

Exit codes

​When to use

​Prerequisites

​Recommended flow

​Command

​Arguments

​Options

​Version strategy

​What happens on deploy

​API key resolution (org-aware)

​Dry-run mode

​Additional files

​Post-deploy files

​Examples

​Output

​Exit codes

When to use

Prerequisites

Recommended flow

Command

Arguments

Options

Version strategy

What happens on deploy

API key resolution (org-aware)

Dry-run mode

Additional files

Post-deploy files

Examples

Output

Exit codes