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
This command does NOT upload local code changes. If you edited config.ts or any file under workflows/, use codika deploy use-case instead. rerun deployment only re-runs the existing remote template with refreshed credentials and optional parameter overrides. Prerequisites
codika CLI installed and authenticated- An existing deployment with
project.json containing devProcessInstanceId or prodProcessInstanceId
- API key with
deploy:use-case scope
Command
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:
--process-instance-id flag (highest priority)project.json field based on --environment:
dev → devProcessInstanceIdprod → prodProcessInstanceId
If neither is found, the command exits with an error.
You can provide parameters in three ways. When multiple methods are used, they are merged with this priority (highest wins):
--param KEY=VALUE flags (repeatable, highest priority)--params '{"key": "value"}' JSON string--params-file ./params.json JSON file (lowest priority)
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.
What happens on rerun
- Load the target process instance from the platform
- Load the deployment template currently associated with the instance
- Merge provided parameters with existing instance parameters
- Refresh workflows — re-run placeholder replacement with updated parameters and current credential state
- 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.
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 instead. 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:
codika rerun deployment --params '{"COMPANY_NAME":"New Corp","LANGUAGE":"fr"}' --json
--param and provides machine-readable output.
Examples
# 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):
{
"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 |
