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

# Rerun Deployment

> Rerun an existing deployment with refreshed credentials and updated parameters, without creating a new template version

## When to use

* Change deployment parameters on a running instance (e.g., company name, language, timezone)
* Retry a failed deployment without creating a new template version
* Apply credential or configuration changes after publishing without bumping the version

<Info>
  **This command does NOT upload local code changes.** If you edited `config.ts` or any file under `workflows/`, use [`codika deploy use-case`](/operations/deploy-use-case) instead. `rerun deployment` only re-runs the existing remote template with refreshed credentials and optional parameter overrides.
</Info>

## Prerequisites

* `codika` CLI installed and authenticated
* An existing deployment with `project.json` containing `devProcessInstanceId` or `prodProcessInstanceId`
* API key with `deploy:use-case` scope

## Command

```bash theme={null}
codika rerun deployment [options]
```

## Options

| Option                       | Description                                      | Default           |
| ---------------------------- | ------------------------------------------------ | ----------------- |
| `--process-instance-id <id>` | Target process instance ID                       | —                 |
| `--path <path>`              | Path to use case folder with `project.json`      | Current directory |
| `--project-file <path>`      | Path to custom project file                      | `project.json`    |
| `--environment <env>`        | Target environment (`dev` or `prod`)             | `dev`             |
| `--param <KEY=VALUE>`        | Set a single parameter (repeatable)              | —                 |
| `--params <json>`            | JSON string with parameters                      | —                 |
| `--params-file <path>`       | Path to JSON file with parameters                | —                 |
| `--force`                    | Force rerun on non-failed instances              | `false`           |
| `--profile <name>`           | Use a specific profile instead of the active one | —                 |
| `--api-url <url>`            | Override API URL                                 | —                 |
| `--api-key <key>`            | Override API key                                 | —                 |
| `--json`                     | JSON output                                      | `false`           |

## Process instance resolution

The CLI resolves which process instance to rerun using this priority:

1. `--process-instance-id` flag (highest priority)
2. `project.json` field based on `--environment`:
   * `dev` → `devProcessInstanceId`
   * `prod` → `prodProcessInstanceId`

If neither is found, the command exits with an error.

## Parameter input methods

You can provide parameters in three ways. When multiple methods are used, they are merged with this priority (highest wins):

1. `--param KEY=VALUE` flags (repeatable, highest priority)
2. `--params '{"key": "value"}'` JSON string
3. `--params-file ./params.json` JSON file (lowest priority)

<Info>
  **Parameters are merged, not replaced.** The CLI sends only the parameters you provide. The platform merges them with the instance's existing parameters. If the instance has `COMPANY_NAME=Acme` and `LANGUAGE=en`, and you pass `--param LANGUAGE=fr`, the result is `COMPANY_NAME=Acme` and `LANGUAGE=fr`. Omitted parameters keep their current values.
</Info>

## What happens on rerun

1. **Load** the target process instance from the platform
2. **Load** the deployment template currently associated with the instance
3. **Merge** provided parameters with existing instance parameters
4. **Refresh** workflows — re-run placeholder replacement with updated parameters and current credential state
5. **Deploy** updated workflows to n8n in-place (preserving existing `n8nWorkflowId` so webhook URLs stay stable)

The instance owner's credentials are used for deployment, not the API key user's. This ensures workflows are deployed with the correct integration bindings.

<Warning>
  Rerunning does **not** create a new template version. The instance continues to run the same template — only the runtime parameters and credentials are refreshed. To deploy new workflow logic, use [`codika deploy use-case`](/operations/deploy-use-case) instead.
</Warning>

## Force flag

| Instance status | `--force` required?                         |
| --------------- | ------------------------------------------- |
| `failed`        | No — failed instances can always be retried |
| `deployed`      | Yes                                         |
| `deploying`     | Yes                                         |
| `user_paused`   | Yes                                         |

## Agent usage

When automating reruns, prefer `--params` with JSON and `--json` for structured output:

```bash theme={null}
codika rerun deployment --params '{"COMPANY_NAME":"New Corp","LANGUAGE":"fr"}' --json
```

This avoids shell escaping issues with `--param` and provides machine-readable output.

## Examples

```bash theme={null}
# Change a single parameter
codika rerun deployment --param COMPANY_NAME="New Corp"

# Multiple parameters (human-friendly)
codika rerun deployment \
  --param COMPANY_NAME="New Corp" \
  --param LANGUAGE=fr \
  --param TIMEZONE="Europe/Paris"

# Agent-friendly JSON
codika rerun deployment --params '{"COMPANY_NAME":"New Corp","LANGUAGE":"fr"}'

# From file
codika rerun deployment --params-file ./updated-params.json

# Retry a failed deployment (no --force needed)
codika rerun deployment --environment dev

# Rerun prod deployment
codika rerun deployment --environment prod --param LANGUAGE=fr --force

# Custom project file
codika rerun deployment --project-file project-client-a.json --param LANGUAGE=fr

# Specific instance ID
codika rerun deployment --process-instance-id pi_abc123 --param LANGUAGE=fr --force

# JSON output for automation
codika rerun deployment --params '{"LANGUAGE":"fr"}' --json
```

## Output

```
✓ Deployment rerun successfully

  Instance:    pi_abc123
  Environment: dev
  Template:    tmpl_def456
  Parameters:  2 updated, 3 unchanged
```

JSON output (`--json`):

```json theme={null}
{
  "success": true,
  "processInstanceId": "pi_abc123",
  "environment": "dev",
  "templateId": "tmpl_def456",
  "parameters": {
    "updated": ["COMPANY_NAME", "LANGUAGE"],
    "unchanged": ["TIMEZONE", "REPORT_EMAIL", "MAX_RETRIES"]
  }
}
```

## 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  | Instance not found           | Check instance ID in `project.json` or pass `--process-instance-id` |
| 409  | Instance not in failed state | Add `--force` to rerun non-failed instances                         |
| 400  | Invalid parameters           | Check parameter names match `INSTPARM` placeholders in the template |

## Exit codes

| Code | Meaning                        |
| ---- | ------------------------------ |
| `0`  | Rerun successful               |
| `1`  | Deployment failed or API error |