Skip to main content

trigger-cloudflow-flow 

dci trigger-cloudflow-flow <flowId> [body]

Starts a run of a published flow whose first node is a webhook, scheduled, or manual trigger. A draft flow is rejected with 422 — use actions/test-run to run one.

No Idempotency-Key is required. This is a state transition, not a resource creation.

The response is a snapshot taken at dispatch, so status is always pending and the timing fields are not yet populated. Read the run back through GET /cloudflow/v1/flows/\{flowId\}/runs/\{runId\} to follow its progress.

A flow holds a concurrency lock while it runs, so triggering one that is already running returns 409 with the active run embedded in the problem body — no second lookup needed.

  • flowId — The ID of the flow to trigger.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Request​

Content-Type: application/json

Raw JSON schema
{
  "type": "object",
  "description": "Optional JSON payload forwarded to the trigger node. Omit or send `{}` for flows\nthat need no input."
}

Output​

The run was started. The snapshot is taken at dispatch, so status is pending.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
idstring
flowIdstring
flowNamestring
statusstringOne of: "pending", "running", "complete", "completed-with-errors", "pending-approval", "failed", "sleeping", "stopped".
isTestbooleanTrue when the run was started through actions/test-run.
triggeredBystring
triggerTimestring (date-time)
startTimestring (date-time)
endTimestring (date-time)
errorstring
stoppedBystring
Raw JSON schema
{
  "type": "object",
  "description": "A run without its per-node detail.",
  "required": [
    "id",
    "flowId",
    "status",
    "isTest",
    "triggeredBy",
    "triggerTime"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "flowId": {
      "type": "string"
    },
    "flowName": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "complete",
        "completed-with-errors",
        "pending-approval",
        "failed",
        "sleeping",
        "stopped"
      ]
    },
    "isTest": {
      "type": "boolean",
      "description": "True when the run was started through `actions/test-run`."
    },
    "triggeredBy": {
      "type": "string"
    },
    "triggerTime": {
      "type": "string",
      "format": "date-time"
    },
    "startTime": {
      "type": "string",
      "format": "date-time"
    },
    "endTime": {
      "type": "string",
      "format": "date-time"
    },
    "error": {
      "type": "string",
      "nullable": true
    },
    "stoppedBy": {
      "type": "string",
      "nullable": true
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
400, 42230VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.
40921RESOURCE_CONFLICTThe operation conflicts with the resource's current state.
42950RATE_LIMITEDToo many requests. Retryable — the CLI reports the server-provided delay.
50040API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: triggercloudflowflow