Skip to main content

​
Usage

codika-helper 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
--path <path>Path to use case folder with project.jsonCurrent directory
--payload <json>Inline JSON payload{}
--payload-file <path>Read payload from a JSON file—
--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—
--jsonJSON output—

​
Process instance ID resolution

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

​
Behavior

​
Fire-and-forget (default)

Returns immediately with the execution ID: 
codika-helper trigger main-workflow --payload '{"query": "test"}'

Triggered: main-workflow
Execution ID: exec_abc123

​
Poll for results (--poll)

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

Triggered: main-workflow
Execution ID: exec_abc123
Polling... (timeout: 120s)

✓ Execution completed (12.3s)
Status:   success
Result:   {"summary": "Analysis complete", "confidence": 95}

​
Payload from file

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

​
Save result to file

codika-helper trigger main-workflow \
  --payload '{"query": "test"}' \
  --poll \
  --output ./result.json

​
Examples

# Simple trigger with inline payload
codika-helper trigger search --payload '{"query": "machine learning"}'

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

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

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

# Save result as JSON
codika-helper trigger main-workflow \
  --poll \
  --json \
  --output result.json

​
Result interpretation

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

​
Error reference

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

​
Important notes

  • Only HTTP-triggered workflows can be triggered via this command
  • The workflowId is the workflowTemplateId from config.ts, not the n8n workflow ID
  • The request wraps your payload in {"payload": {...}}
  • Execution is asynchronous — the trigger returns immediately unless --poll is used