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

# Publish Use Case

> Promote a deployed use case from dev to production, set visibility and sharing, and manage dev/prod instance toggling

## When to use

* Promote a deployed use case from dev to production
* Make a process available to end users for the first time
* Configure visibility (private, organizational, public) on first publish
* Enable dev/prod auto-toggle to pause dev when prod is running

## Prerequisites

* `codika` CLI installed and authenticated
* A deployed use case with `project.json` containing a `deployments` map (run `deploy use-case` first)
* API key with `deploy:use-case` scope

## Command

```bash theme={null}
codika publish <templateId> [options]
```

## Arguments

| Argument       | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| `<templateId>` | Deployment template ID (from `project.json` deployments map) |

## Options

| Option                   | Description                                                   | Default                       |
| ------------------------ | ------------------------------------------------------------- | ----------------------------- |
| `--path <path>`          | Path to use case folder with project.json                     | Current directory             |
| `--project-file <path>`  | Custom project file path                                      | `project.json`                |
| `--project-id <id>`      | Override project ID                                           | `project.json`                |
| `--visibility <scope>`   | `private`, `organizational`, or `public` (first publish only) | —                             |
| `--shared-with <scope>`  | `owner_only`, `admins`, or `everyone` (org processes only)    | —                             |
| `--auto-toggle-dev-prod` | Pause dev instance when prod is active                        | Off (both run simultaneously) |
| `--skip-prod-instance`   | Don't auto-create/update prod instance                        | —                             |
| `--api-url <url>`        | Override API URL                                              | —                             |
| `--api-key <key>`        | Override API key                                              | —                             |
| `--profile <name>`       | Use a specific profile instead of the active one              | —                             |
| `--json`                 | JSON output                                                   | —                             |

## Finding the template ID

After each deploy, `project.json` stores a `deployments` map keyed by version:

```json theme={null}
{
  "projectId": "abc123",
  "devProcessInstanceId": "pi_dev_456",
  "deployments": {
    "1.0": { "templateId": "tmpl_abc", "createdAt": "2026-03-04T14:30:00Z" },
    "1.1": { "templateId": "tmpl_def", "createdAt": "2026-03-04T15:00:00Z" }
  }
}
```

Use the `templateId` from the version you want to publish.

## What happens on publish

1. **Resolve** project ID: `--project-id` > `--project-file` > `project.json`
2. **Resolve** API key: `--api-key` > env > active profile
3. **Send** publish request to platform with templateId, projectId, and options
4. **Platform** publishes the deployment template (status: inactive → published)
5. **Platform** deprecates any previously published templates for this project
6. **Platform** auto-creates or updates the owner's prod process instance
7. If `--auto-toggle-dev-prod`, deactivates dev instance
8. **On success:** saves `prodProcessInstanceId` to `project.json`

## Visibility

Set on first publish only. Subsequent publishes inherit the existing visibility.

| Level            | Who can see and install |
| ---------------- | ----------------------- |
| `private`        | Only the owner          |
| `organizational` | All org members         |
| `public`         | Anyone on the platform  |

## Shared with

Controls who can use the prod instance. Applies to organizational processes only.

| Scope        | Who can use the prod instance                   |
| ------------ | ----------------------------------------------- |
| `owner_only` | Only the process owner                          |
| `admins`     | Organization admins (default for org processes) |
| `everyone`   | All organization members                        |

## Dev/Prod toggle

By default, both dev and prod instances run simultaneously. Use `--auto-toggle-dev-prod` to pause the dev instance when production becomes active:

```bash theme={null}
codika publish tmpl_abc123 --auto-toggle-dev-prod
```

This keeps production as the single active instance, avoiding duplicate executions from scheduled or webhook triggers.

To disable the toggle after publishing, re-publish without the flag or update the setting in the platform UI.

## Examples

```bash theme={null}
# Publish the latest deployment
codika publish tmpl_abc123

# Publish with visibility (first publish)
codika publish tmpl_abc123 --visibility organizational --shared-with admins

# Publish from a specific directory
codika publish tmpl_abc123 --path ./my-use-case

# JSON output
codika publish tmpl_abc123 --json

# Pause dev when prod runs
codika publish tmpl_abc123 --auto-toggle-dev-prod
```

## Output

```
✓ Published successfully!

  Version:              1.1
  Template ID:          tmpl_abc123
  Prod Instance ID:     pi_prod_789
  Webhook URL:          https://...
```

<Info>
  **Need to change parameters without a new version?** After publishing, use [`codika rerun deployment`](/operations/rerun-deployment) to update deployment parameters on the prod instance without creating a new template version. Only the parameters you specify are changed — everything else stays the same.
</Info>

## Error reference

| HTTP | Error              | Fix                                                 |
| ---- | ------------------ | --------------------------------------------------- |
| 401  | Invalid API key    | Re-login with `codika login`                        |
| 403  | Missing scope      | Create key with `deploy:use-case` scope             |
| 404  | Template not found | Check templateId in project.json deployments        |
| 400  | Invalid status     | Template already published or not in inactive state |

## Exit codes

| Code | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| `0`  | Publish successful                                       |
| `1`  | API error                                                |
| `2`  | CLI validation error (missing templateId, no project ID) |