> ## Documentation Index
> Fetch the complete documentation index at: https://doc.codika.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Use Case

> Deploy a use case folder to the Codika platform with version management, agent skill collection, deployment archiving, and org-aware API key resolution

## 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

```bash theme={null}
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

```bash theme={null}
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

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](/concepts/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

<Info>
  **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.
</Info>

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

<Info>
  **For parameter-only changes**, use [`codika rerun deployment`](/operations/rerun-deployment) instead. It updates deployment parameters on an existing instance without creating a new template version — no version bump, no new deployment archive.
</Info>

## 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:

```bash theme={null}
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):

```bash theme={null}
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
```

<Note>
  Data ingestion workflows live in a separate `data-ingestion/` folder and are deployed independently via [`codika deploy process-data-ingestion`](/operations/deploy-data-ingestion). They have their own version line and do not trigger "update available" notifications.
</Note>

## Examples

```bash theme={null}
# 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 |