trigger

Execute a deployed workflow via its HTTP webhook, optionally polling for results

Usage

codika-helper trigger <workflowId> [options]

Arguments

Argument	Description
<workflowId>	The workflowTemplateId from config.ts

Options

Option	Description	Default
--process-instance-id <id>	Explicit process instance ID	Auto-resolved from project.json
--path <path>	Path to use case folder with project.json	Current directory
--payload-file <path>	Read payload from a JSON file, or - for stdin	—
--poll	Wait for execution to complete	Fire-and-forget
--timeout <seconds>	Max poll time	120
-o, --output <path>	Save result to file (with --poll)	stdout
--api-url <url>	Override API URL	—
--api-key <key>	Override API key	—
--json	JSON 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

✓ Workflow triggered

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

  Poll for status:
    codika-helper get execution exec_abc123

Poll for results (--poll)

Waits for the execution to complete, polling every 3-5 seconds:

codika-helper 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

Payload via stdin (recommended)

Use --payload-file - with a heredoc to pass JSON without shell escaping issues:

codika-helper 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-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 --poll -o ./result.json --payload-file - <<'EOF'
{"query": "test"}
EOF

Examples

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

# 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 \
  --poll --payload-file - <<'EOF'
{"text": "hello"}
EOF

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

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

Result interpretation

Status	Meaning	Data field
success	Workflow completed successfully	resultData contains output
failed	Workflow encountered an error	errorDetails.message describes failure
pending	Still running (only seen during polling)	—

Error reference

HTTP	Error	Cause	Fix
401	Invalid API key	Wrong or expired key	codika-helper whoami, then codika-helper login
403	Missing scope	Key lacks workflows:trigger	Create new key with scope
403	No access	Process in different org	codika-helper use <profile>
404	Workflow not found	Wrong workflowId	Check config.ts workflowTemplateId
412	Instance inactive	Process paused or failed	Re-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