> ## Documentation Index
> Fetch the complete documentation index at: https://doc.codika.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Workflow

> Execute a deployed workflow (HTTP or scheduled) via the CLI, with payload support, polling for results, and process instance ID resolution

## 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

```bash theme={null}
codika 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` |
| `--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.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                                            | —                                 |
| `--profile <name>`           | Use a specific profile instead of the active one            | —                                 |
| `--json`                     | JSON 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:

```bash theme={null}
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:

```bash theme={null}
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
```

### Payload via stdin (recommended)

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

```bash theme={null}
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

```bash theme={null}
codika trigger main-workflow --payload-file ./test-input.json --poll
```

The file must contain a JSON object.

### Save result to file

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

## Result statuses

| 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) | —                                        |

## Examples

```bash theme={null}
# 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

| HTTP | Error              | Cause                         | Fix                                  |
| ---- | ------------------ | ----------------------------- | ------------------------------------ |
| 401  | Invalid API key    | Wrong or expired key          | `codika whoami`, then `codika login` |
| 403  | Missing scope      | Key lacks `workflows:trigger` | Create new key with scope            |
| 403  | No access          | Process in different org      | `codika 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

* 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