Workflow commands
Command reference for workflows list, get, estimate and run, and runs list, get and cancel.
A workflow is a ready-made multi-step pipeline you run with one command: for example, an idea in, a still image, a 5-second clip and a cover frame out. See Workflows.
windpaint workflows get text-to-clip
windpaint workflows run text-to-clip -i idea="a paper boat drifting down a rainy street" -o ./clip/
workflows has the alias workflows.
workflows
windpaint workflows
windpaint workflows --category video
Lists workflows with their visible inputs and the credit estimate at default inputs. workflows list also works.
WORKFLOW NAME CATEGORY AVAILABLE CREDITS INPUTS
text-to-clip Text to Clip video yes 4.08 aspect,idea
photo-to-clip Photo to Clip video no - look,motion,photo
...
| Flag | Description |
|---|---|
--category <category> | Only workflows in this category: image, video or audio. |
text-to-clip is available today. Other workflows in the catalog show AVAILABLE no until the models they need are live; running them fails with exit code 8.
workflows get
windpaint workflows get text-to-clip
Shows a workflow’s input form, outputs, steps and estimate. Alias show.
Workflow text-to-clip
Name Text to Clip
Category video
Description Describe a moment; get a still, a 5 s clip and a cover frame.
Available yes
Credits 4.08 (estimate at defaults)
Outputs video, still, cover
Inputs (-i name=value):
INPUT TYPE REQUIRED DEFAULT OPTIONS LABEL
aspect choice no 16:9 16:9|9:16 Aspect ratio
idea text yes - - What should happen?
Steps:
STEP CAPABILITY/OP MODEL
still image.generate z-image-turbo
frame image.resize -
clip video.generate wan-2.2-i2v
cover video.extract_frame -
Read the Inputs table before running a workflow you haven’t used: it has the names to pass with -i, their types and the allowed options. Steps without a model are local operations and cost nothing.
workflows estimate
windpaint workflows estimate text-to-clip -i idea="a paper boat" -i aspect=9:16
Prices a run with these inputs without starting it.
Workflow text-to-clip
Credits 4.08
Available yes
| Flag | Description |
|---|---|
-i, --input <name=value> | Workflow input. Repeatable. |
Unlike windpaint estimate, this uploads local files given for media inputs. Uploads are free.
workflows run
windpaint workflows run text-to-clip -i idea="a paper boat drifting down a rainy street" -o ./clip/
windpaint workflows run text-to-clip -i idea="neon koi in a puddle" -i aspect=9:16 --no-wait
Starts a run, waits for it with step progress on stderr, and prints the run with its steps and outputs. With -o it downloads every output.
While waiting, it first asks the API to hold the start request until the run finishes, for up to --timeout or 60 seconds, whichever is shorter, then polls; the total wait can reach --timeout plus 60 seconds. The progress line shows the run’s percentage while it’s running. The start request carries an Idempotency-Key and is retried with the same key on a network error, so one command never starts two runs.
Started run 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f (text-to-clip, estimate 4.08 credits)
run 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f completed in 3m02s
Saved clip/cover.png
Saved clip/still.png
Saved clip/video.mp4
Run 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f
Workflow text-to-clip
Status completed
Credits 4.08 charged
STEP STATUS CAPABILITY/OP REQUEST ERROR
still completed image.generate 0b6e2f4a-91c3-4d8e-a5f7-3c2d1e0f9a8b -
frame completed image.resize - -
clip completed video.generate 3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60 -
cover completed video.extract_frame - -
OUTPUT ASSET TYPE LOCATION
cover 5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d image/png /Users/you/clip/cover.png
still 7d2c9e1a-5b3f-4a6d-8e0c-1f2a3b4c5d6e image/png /Users/you/clip/still.png
video d41e8b0c-2a3f-4c5d-9e6f-7a8b9c0d1e2f video/mp4 /Users/you/clip/video.mp4
| Flag | Description |
|---|---|
-i, --input <name=value> | Workflow input. Repeatable. |
-o, --output <dir> | Download outputs into this directory. Always treated as a directory and created if missing. |
--force | Overwrite existing files. |
--no-wait | Return after starting the run. |
--timeout <duration> | How long to wait. Default 30m; 0 waits forever. |
Input values
Each -i name=value is typed by the workflow’s input form:
| Input type | Value |
|---|---|
image, video, audio | One local file (uploaded for you), @path, an asset id, an asset URL, a public https:// URL or a data: URI. Same rules as run inputs, but one value only. |
number | A number, e.g. -i strength=0.6 |
choice | One of the listed options, e.g. -i aspect=9:16 |
text | Any string. Quote it if it has spaces. |
An input name the workflow doesn’t have fails with exit code 2 and lists the valid names. Omitted inputs take their defaults; a missing required input is rejected by the API with exit code 6.
Output files
Files are named after the workflow’s outputs, with the extension from the content type: text-to-clip with -o ./clip/ saves clip/video.mp4, clip/still.png and clip/cover.png. If one output has several files, they’re saved as <output>-1.<ext>, <output>-2.<ext>, … Existing files are never overwritten without --force.
How it ends
| Outcome | Exit code |
|---|---|
Run completed | 0 |
Run failed or canceled | 9. The run, with each step’s error, is on stdout. |
Still running after --timeout | 10. Continue with windpaint runs get <run-id> --wait. |
| Ctrl-C | 130. The run keeps going; stop it with windpaint runs cancel <run-id>. |
Starting a run checks your balance against the estimate but doesn’t reserve it. Each step holds its own credits when it starts, so a run can fail partway if your balance runs out. Steps that completed are charged; the rest are not. The CLI has no webhook flag for workflow runs; to get a signed webhook when a run finishes, start it through the API with webhook_url.
runs
windpaint runs
windpaint runs --workflow text-to-clip -n 50
Lists workflow runs in the selected project, newest first. runs list also works.
RUN WORKFLOW STATUS CREDITS CREATED
9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f text-to-clip completed 4.08 2026-10-04 14:20
| Flag | Description |
|---|---|
-n, --limit <n> | Maximum rows, 1–200. Default 20. |
--workflow <slug> | Only runs of this workflow. |
To see the individual generation jobs a run made, use windpaint requests --run <run-id>.
runs get
windpaint runs get 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f
windpaint runs get 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f --wait -o ./clip/
Shows a run with its steps and outputs. Run status is one of queued, running, completed, failed or canceled; each step is pending, running, completed, failed or canceled.
| Flag | Description |
|---|---|
-w, --wait | Wait until the run finishes, with the same exit codes as workflows run. |
--timeout <duration> | How long to wait. Default 30m; 0 waits forever. |
-o, --output <dir> | With --wait, download outputs into this directory. Ignored without --wait. |
--force | Overwrite existing files. |
runs cancel
windpaint runs cancel 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f
Cancels an unfinished run and its pending steps, and prints the run.