When to use
- Change deployment parameters on a running instance (e.g., company name, language, timezone)
- Retry a failed deployment without redeploying the entire use case
- Apply configuration changes after publishing without creating a new version
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 redeploy [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 redeploy 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 redeploy 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 redeploy
- 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
- Deploy updated workflows to n8n (using the instance owner’s credentials)
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.
Redeploying does not create a new template version. The instance continues to run the same template — only the runtime parameters change. 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 redeploy, prefer --params with JSON and --json for structured output:
codika redeploy --params '{"COMPANY_NAME":"New Corp","LANGUAGE":"fr"}' --json
--param and provides machine-readable output.
Examples
# Change a single parameter
codika redeploy --param COMPANY_NAME="New Corp"
# Multiple parameters (human-friendly)
codika redeploy \
--param COMPANY_NAME="New Corp" \
--param LANGUAGE=fr \
--param TIMEZONE="Europe/Paris"
# Agent-friendly JSON
codika redeploy --params '{"COMPANY_NAME":"New Corp","LANGUAGE":"fr"}'
# From file
codika redeploy --params-file ./updated-params.json
# Retry a failed deployment (no --force needed)
codika redeploy --environment dev
# Redeploy prod instance
codika redeploy --environment prod --param LANGUAGE=fr --force
# Custom project file
codika redeploy --project-file project-client-a.json --param LANGUAGE=fr
# Specific instance ID
codika redeploy --process-instance-id pi_abc123 --param LANGUAGE=fr --force
# JSON output for automation
codika redeploy --params '{"LANGUAGE":"fr"}' --json
Output
✓ Redeployed 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 redeploy non-failed instances |
| 400 | Invalid parameters | Check parameter names match INSTPARM placeholders in the template |
Exit codes
| Code | Meaning |
|---|
0 | Redeploy successful |
1 | Deployment failed or API error |
