Workflow commands

Validate and deploy workflow files, start and watch runs, retry or cancel them, roll a definition back, and read and write a workflow’s stored state.

Workflows run on Tangle Platform, so --base-url on these commands points at the Platform host. TANGLE_PLATFORM_URL sets it for every command, and TANGLE_HUB_URL does inside a sandbox.

tangle workflows validate hello.yml
tangle workflows apply hello.yml
tangle workflows run wf_abc --wait
tangle workflows get wf_abc --yaml > hello.yml

workflows get <id> --yaml prints the definition in a form apply and update accept, so you can export, edit and re-apply it. Workflows introduces workflows; Workflow YAML reference documents every field.

Commands on this page

Command	What it does
`tangle workflows list`	List your workflows
`tangle workflows fleet`	Fleet overview: every workflow’s run tallies over a trailing window, failing-first
`tangle workflows get`	Show a workflow’s definition and compiled triggers
`tangle workflows create`	Create a workflow from a YAML file
`tangle workflows apply`	Create or update a workflow idempotently, matched by the definition’s name
`tangle workflows update`	Replace a workflow’s definition from a YAML file
`tangle workflows delete`	Delete a workflow and its triggers
`tangle workflows validate`	Validate a workflow YAML file without saving it
`tangle workflows schema`	Print the JSON Schema for the workflow YAML
`tangle workflows run`	Trigger an immediate run of a workflow
`tangle workflows runs`	List a workflow’s run history (newest first)
`tangle workflows run-detail`	Show a single run’s detail (per-action output and errors)
`tangle workflows cancel`	Cancel a queued or in-progress run
`tangle workflows retry`	Re-run a failed or cancelled run (a fresh run with the same trigger context)
`tangle workflows events`	Tail a run’s live progress events until it finishes
`tangle workflows enable`	Enable a workflow so its triggers and manual runs fire
`tangle workflows disable`	Disable a workflow (pause its triggers and manual runs)
`tangle workflows templates`	List the curated starter workflow templates
`tangle workflows init`	Create a workflow from a gallery template and print (or save) its YAML
`tangle workflows revisions`	List a workflow’s definition revision history (newest first)
`tangle workflows revision`	Show one revision’s metadata and definition YAML
`tangle workflows rollback`	Restore a prior revision’s definition as a NEW head revision (re-validated)
`tangle workflows kv list`	List every KV entry of a workflow
`tangle workflows kv get`	Show one KV entry (value and version)
`tangle workflows kv set`	Write a KV entry from a JSON value
`tangle workflows kv delete`	Delete a KV entry (idempotent)
`tangle workflows artifacts`	List a run’s artifact metadata (never the bytes)
`tangle workflows artifact-download`	Download one run artifact’s bytes to a file
`tangle workflows decisions`	List a workflow’s pending human decisions
`tangle workflows decision-resolve`	Answer the decision a run is parked on and resume it

Definitions

`tangle workflows list`

List your workflows.

Lists your workflows.

tangle workflows list

Request: GET /v1/workflows

tangle workflows list

`tangle workflows fleet`

Fleet overview: every workflow’s run tallies over a trailing window, failing-first.

tangle workflows fleet [options]

Flag	Default	Description
`--window <window>`	`7d`	Trailing window: 24h, 7d, or 30d

Request: GET /v1/workflows/insights/fleet

tangle workflows fleet

`tangle workflows get`

Show a workflow’s definition and compiled triggers.

Shows a workflow’s definition and compiled triggers; --yaml prints only the definition.

tangle workflows get <id> [options]

Flag	Default	Description
`--yaml`		Print only the raw definition YAML (the export path, pipe to a file)

Request: GET /v1/workflows/{id}

tangle workflows get wf_abc --yaml

`tangle workflows create`

Create a workflow from a YAML file.

tangle workflows create <file>

Request: POST /v1/workflows

tangle workflows create hello.yml

`tangle workflows apply`

Create or update a workflow idempotently, matched by the definition’s name.

tangle workflows apply <file>

Request: POST /v1/workflows

tangle workflows apply ~/flow.yaml --json

`tangle workflows update`

Replace a workflow’s definition from a YAML file.

tangle workflows update <id> <file> [options]

Flag	Default	Description
`--note <note>`		Revision note recorded on the appended revision (why this change)

Request: PUT /v1/workflows/{id}

tangle workflows update wf_abc ~/flow.yaml --json

`tangle workflows delete`

Delete a workflow and its triggers.

tangle workflows delete <id> [options]

Flag	Default	Description
`--force`		Skip confirmation prompt

Request: DELETE /v1/workflows/{id}

tangle workflows delete wf_abc

`tangle workflows validate`

Validate a workflow YAML file without saving it.

tangle workflows validate <file> [options]

Flag	Default	Description
`--structural`		CI mode: compile + capability checks only, no connection resolution, the verdict is the same regardless of connected providers

Request: POST /v1/workflows/validate

tangle workflows validate ~/flow.yaml

`tangle workflows schema`

Print the JSON Schema for the workflow YAML.

Prints the workflow YAML JSON Schema.

tangle workflows schema

Request: GET /v1/workflows/schema

tangle workflows schema

Runs

`tangle workflows run`

Trigger an immediate run of a workflow.

Triggers a run; --wait polls until it finishes and prints the result.

tangle workflows run <id> [options]

Flag	Default	Description
`--input-file <file>`		Trigger inputs from a flat JSON string map; `--input` overrides its keys
`--input <key=value>`		Trigger input as key=value (e.g. pull_request.number=123). Repeatable.
`--wait`		Wait for the run to finish and print its result
`--timeout <ms>`		With `--wait`, fail if the run has not finished after this many milliseconds
`--poll-interval <ms>`		With `--wait`, how often to poll for completion (default 2000)

Request: POST /v1/workflows/{id}/run

tangle workflows run wf_abc --json

`tangle workflows runs`

List a workflow’s run history (newest first).

Lists a workflow’s runs, newest first.

tangle workflows runs <id> [options]

Flag	Default	Description
`--limit <n>`		Runs per page (1-100)
`--cursor <cursor>`		Pagination cursor from a previous page
`--all`		Fetch every page, not just the first

Request: GET /v1/workflows/{id}/runs

tangle workflows runs wf_abc

`tangle workflows run-detail`

Show a single run’s detail (per-action output and errors).

Shows one run’s per-action output and errors.

tangle workflows run-detail <id> <runId>

Request: GET /v1/workflows/{id}/runs/{runId}

tangle workflows run-detail wf_abc run_1

`tangle workflows cancel`

Cancel a queued or in-progress run.

Cancels a queued or running run.

tangle workflows cancel <id> <runId>

Request: POST /v1/workflows/{id}/runs/{runId}/cancel

tangle workflows cancel wf_abc run_1

`tangle workflows retry`

Re-run a failed or cancelled run (a fresh run with the same trigger context).

tangle workflows retry <id> <runId> [options]

Flag	Default	Description
`--wait`		Wait for the new run to finish and print its result
`--timeout <ms>`		With `--wait`, fail if the run has not finished after this many milliseconds
`--poll-interval <ms>`		With `--wait`, how often to poll for completion (default 2000)

Request: POST /v1/workflows/{id}/runs/{runId}/retry

tangle workflows retry wf_abc run_1

`tangle workflows events`

Tail a run’s live progress events until it finishes.

tangle workflows events <id> <runId>

Request: GET /v1/workflows/{id}/runs/{runId}/events

tangle workflows events wf_abc run_1

`tangle workflows enable`

Enable a workflow so its triggers and manual runs fire.

Enables a workflow’s triggers and manual runs.

tangle workflows enable <id>

Request: PATCH /v1/workflows/{id}

tangle workflows enable wf_abc --json

`tangle workflows disable`

Disable a workflow (pause its triggers and manual runs).

Pauses a workflow’s triggers and manual runs.

tangle workflows disable <id>

Request: PATCH /v1/workflows/{id}

tangle workflows disable wf_abc

Templates

`tangle workflows templates`

List the curated starter workflow templates.

Lists the starter workflow templates.

tangle workflows templates

Request: GET /v1/workflows/templates

tangle workflows templates

`tangle workflows init`

Create a workflow from a gallery template and print (or save) its YAML.

Creates a workflow from a gallery template and prints or saves its YAML.

tangle workflows init <template-id> [options]

Flag	Default	Description
`--param <key=value>`		Template parameter value. Repeatable.
`--file <out>`		Write the instantiated workflow YAML to this file instead of stdout

Request: POST /v1/workflows/templates/{templateId}/instantiate

tangle workflows init pr-review --file ~/out.yml

Revisions

`tangle workflows revisions`

List a workflow’s definition revision history (newest first).

Lists a workflow’s definition revisions.

tangle workflows revisions <id>

Request: GET /v1/workflows/{id}/revisions

tangle workflows revisions wf_abc

`tangle workflows revision`

Show one revision’s metadata and definition YAML.

Shows one revision’s metadata and YAML.

tangle workflows revision <id> <rev>

Request: GET /v1/workflows/{id}/revisions/{rev}

tangle workflows revision wf_abc 3

`tangle workflows rollback`

Restore a prior revision’s definition as a NEW head revision (re-validated).

tangle workflows rollback <id> <rev>

Request: POST /v1/workflows/{id}/rollback

tangle workflows rollback wf_abc 2 --json

Key-value state

`tangle workflows kv list`

List every KV entry of a workflow.

Lists every KV entry.

tangle workflows kv list <id>

Request: GET /v1/workflows/{id}/kv

tangle workflows kv list wf_abc

`tangle workflows kv get`

Show one KV entry (value and version).

Shows one KV entry’s value and version.

tangle workflows kv get <id> <key>

Request: GET /v1/workflows/{id}/kv/{key}

tangle workflows kv get wf_abc cursor --json

`tangle workflows kv set`

Write a KV entry from a JSON value.

Writes a KV entry from a JSON value; --cas writes only if the version still matches.

tangle workflows kv set <id> <key> <json> [options]

Flag	Default	Description
`--cas <version>`		Compare-and-swap: write only if the stored version still equals this

Request: PUT /v1/workflows/{id}/kv/{key}

tangle workflows kv set wf_abc cursor '{"cursor":123}'

With --cas the request is POST /v1/workflows/{id}/kv/{key}/cas.

`tangle workflows kv delete`

Delete a KV entry (idempotent).

Deletes a KV entry; idempotent.

tangle workflows kv delete <id> <key>

Request: DELETE /v1/workflows/{id}/kv/{key}

tangle workflows kv delete wf_abc cursor --json

Artifacts

`tangle workflows artifacts`

List a run’s artifact metadata (never the bytes).

Lists a run’s artifact metadata.

tangle workflows artifacts <id> <runId>

Request: GET /v1/workflows/{id}/runs/{runId}/artifacts

tangle workflows artifacts wf_abc run_1

`tangle workflows artifact-download`

Download one run artifact’s bytes to a file.

tangle workflows artifact-download <id> <runId> <artifactId> [options]

Flag	Default	Description
`--out <file>`		Destination file (defaults to the artifact ID)

Request: GET /v1/workflows/{id}/runs/{runId}/artifacts/{artifactId}

tangle workflows artifact-download wf_abc run_1 art_1 --out ~/out.bin

Human decisions

`tangle workflows decisions`

List a workflow’s pending human decisions.

Lists pending human decisions.

tangle workflows decisions <id>

Request: GET /v1/workflows/decisions/pending

tangle workflows decisions wf_abc

`tangle workflows decision-resolve`

Answer the decision a run is parked on and resume it.

tangle workflows decision-resolve <id> <runId> [options]

Flag	Default	Description
`--choice <choice>`		The option to resolve with (one of the decision’s options). Required.

Request: POST /v1/workflows/{id}/runs/{runId}/decision/resolve

tangle workflows decision-resolve wf_abc run_1 --choice deploy --json

Sandbox commands File, git, process and preview commands

Workflow commands

Commands on this page

Definitions

tangle workflows list

tangle workflows fleet

tangle workflows get

tangle workflows create

tangle workflows apply

tangle workflows update

tangle workflows delete

tangle workflows validate

tangle workflows schema

Runs

tangle workflows run

tangle workflows runs

tangle workflows run-detail

tangle workflows cancel

tangle workflows retry

tangle workflows events

tangle workflows enable

tangle workflows disable