Skip to main content

​
When to use

  • Test a deployed workflow
  • Execute a workflow via the CLI instead of the platform UI
  • Automate workflow execution in scripts or CI

​
Prerequisites

  • Use case deployed (project.json contains devProcessInstanceId)
  • Authenticated via codika login or CODIKA_API_KEY env var
  • API key with workflows:trigger scope

​
Resolving the workflow ID

The workflowId is the workflowTemplateId from config.ts. If the user provides a use case folder path, read config.ts to find the available workflow IDs and their trigger types. Supported trigger types:
  • HTTP triggers (trigger.type === 'http'): Triggered with optional payload
  • Schedule triggers (trigger.type === 'schedule'): Triggered via the manualTriggerUrl configured in config.ts. The CLI creates an execution document upfront and passes it to the workflow, so --poll works exactly like HTTP triggers. No payload is needed.

​
Command

codika trigger <workflowId> [options]

​
Arguments

ArgumentDescription
<workflowId>The workflowTemplateId from config.ts

​
Options

OptionDescriptionDefault
--process-instance-id <id>Explicit process instance IDAuto-resolved from project.json
--project-file <path>Path to custom project file (e.g., project-client-a.json)project.json
--path <path>Path to use case folder with project.jsonCurrent directory
--payload-file <path>Read payload from a JSON file, or - for stdin—
--pollWait for execution to completeFire-and-forget
--timeout <seconds>Max poll time120
-o, --output <path>Save result to file (with --poll)stdout
--api-url <url>Override API URL—
--api-key <key>Override API key—
--profile <name>Use a specific profile instead of the active one—
--jsonJSON output—

​
Process instance ID resolution

  1. --process-instance-id flag (highest priority)
  2. devProcessInstanceId in --project-file (if provided)
  3. devProcessInstanceId in project.json at --path
  4. devProcessInstanceId in project.json in current directory

​
Behavior

​
Fire-and-forget (default)

Returns immediately with the execution ID: 
codika trigger main-workflow

✓ Workflow triggered

  Execution ID:      exec_abc123
  Process Instance:  pi_def456
  Workflow:          main-workflow

  Poll for status:
    codika get execution exec_abc123

​
Poll for results (--poll)

Waits for the execution to complete, polling every 3-5 seconds: 
codika trigger main-workflow --poll --payload-file - <<'EOF'
{"query": "test"}
EOF

✓ Workflow triggered (execution: exec_abc123)

✓ Execution success (2.3s)

  Result:
  {
    "summary": "Analysis complete",
    "confidence": 95
  }

  Execution ID: exec_abc123
Use --payload-file - with a heredoc to pass JSON without shell escaping issues: 
codika trigger main-workflow --poll --payload-file - <<'EOF'
{"query": "machine learning", "maxResults": 10}
EOF
This is the recommended approach when calling from scripts or AI agents, as it avoids shell quoting problems with nested JSON.

​
Payload from file

codika trigger main-workflow --payload-file ./test-input.json --poll
The file must contain a JSON object.

​
Save result to file

codika trigger main-workflow --poll -o ./result.json --payload-file - <<'EOF'
{"query": "test"}
EOF

​
Result statuses

StatusMeaningData field
successWorkflow completed successfullyresultData contains output
failedWorkflow encountered an errorerrorDetails.message describes failure
pendingStill running (only seen during polling)—

​
Examples

# Trigger with heredoc payload and poll
codika trigger search --poll --payload-file - <<'EOF'
{"query": "machine learning"}
EOF

# Trigger with payload file and poll
codika trigger analyze \
  --payload-file input.json \
  --poll \
  --timeout 300

# Trigger from a different directory
codika trigger main-workflow \
  --path ./my-use-case \
  --poll --payload-file - <<'EOF'
{"text": "hello"}
EOF

# Explicit process instance ID
codika trigger main-workflow \
  --process-instance-id pi_abc123 \
  --poll --payload-file - <<'EOF'
{"text": "hello"}
EOF

# JSON output for scripting
codika trigger main-workflow \
  --poll \
  --json \
  --payload-file - <<'EOF'
{"text": "test"}
EOF

# Trigger a scheduled workflow manually (no payload needed)
codika trigger daily-report --poll

​
Error reference

HTTPErrorCauseFix
401Invalid API keyWrong or expired keycodika whoami, then codika login
403Missing scopeKey lacks workflows:triggerCreate new key with scope
403No accessProcess in different orgcodika use <profile>
404Workflow not foundWrong workflowIdCheck config.ts workflowTemplateId
412Instance inactiveProcess paused or failedRe-deploy or check platform

​
Important notes

  • Both HTTP and schedule triggers are supported
  • Schedule triggers require a manualTriggerUrl in config.ts (with a matching Webhook node in the workflow JSON)
  • The workflowId is the workflowTemplateId from config.ts, not the n8n workflow ID
  • For HTTP triggers: the request wraps your payload in {"payload": {...}}
  • For schedule triggers: no payload needed (the workflow runs its own logic)
  • Execution is asynchronous — the trigger returns immediately unless --poll is used
  • --poll works for both trigger types
  • File uploads are not supported via CLI — use the platform UI