Skip to main content

​
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)
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

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

​
Options

OptionDescriptionDefault
--api-url <url>Codika API URLCODIKA_API_URL env or profile
--api-key <key>Codika API keyCODIKA_API_KEY env or profile
--project-id <id>Override project IDproject.json or config.ts
--project-file <path>Path to custom project file (e.g., project-client-a.json)project.json
--patchPatch version bumpDefault
--minorMinor version bump—
--majorMajor version bump—
--target-version <X.Y>Explicit API version—
--additional-file <abs:rel>Add extra file (repeatable)—
--jsonJSON output—
--profile <name>Use a specific profile instead of the active one—
--dry-runPreview without calling API—

​
Version strategy

FlagLocal version changeAPI version strategy
--patch (default)1.0.0 → 1.0.1minor_bump
--minor1.0.1 → 1.1.0minor_bump
--major1.1.0 → 2.0.0major_bump
--target-version 3.0Unchangedexplicit (version 3.0)

​
What happens on deploy

  1. Read version.json for current version
  2. Validate the use case (same as verify use-case)
  3. Bump version based on flags
  4. Resolve project ID: --project-id > --project-file > project.json > config.ts
  5. Resolve API key: --api-key > env > org-matching profile > active profile
  6. Package all workflow files
  7. Send to the Codika platform API
  8. Collect agent skills from skills/*/SKILL.md (if any exist)
  9. 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 redeploy 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:
  1. --api-key flag (always wins)
  2. CODIKA_API_KEY environment variable
  3. Profile matching organizationId from project.json
  4. 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

CodeMeaning
0Deployment successful
1API error or validation failure