Skip to main content

Using the CLI

This guide covers the typical developer workflow for building and running Zigflow workflows. For the complete flag reference, see the autogenerated CLI reference.

Typical workflow​

1. Write a workflow file​

Create a YAML file that describes your workflow. See the DSL reference for the full schema.

2. Validate​

Check the workflow for errors before running it:

zigflow validate workflow.yaml

Exits with code 0 if valid. Prints a human-readable error and exits with a non-zero code if invalid. No Temporal connection is required.

It also prints warnings for workflows that are valid but probably do not do what was meant, such as a do task in a task list that also contains other tasks, when no switch case redirects to it (WARN_NESTED_DO_DEFINITION). Zigflow treats that do as a separate workflow definition: it runs inline only if it comes before the first other task, and is skipped if it comes after one. Warnings do not change the exit code, and appear under warnings in the JSON output.

Use --output-json for machine-readable output:

zigflow validate workflow.yaml --output-json

3. Run the worker​

zigflow run -f workflow.yaml

This starts a Temporal worker that:

  • Connects to Temporal (default: localhost:7233)
  • Registers the compiled workflow on the task queue defined by document.taskQueue
  • Polls Temporal until interrupted

4. Trigger the workflow​

Zigflow does not include a trigger command. Use the Temporal CLI to start executions:

temporal workflow start \
  --type your-workflow-name \
  --task-queue your-namespace \
  --workflow-id my-run-1

Pass input with --input:

temporal workflow start \
  --type your-workflow-name \
  --task-queue your-namespace \
  --workflow-id my-run-1 \
  --input '{"userId": 42}'

5. View results​

temporal workflow show --workflow-id my-run-1

Validation in CI​

zigflow validate exits with a non-zero code on failure, which fails the pipeline step. Example GitHub Actions step:

- name: Validate workflow
  run: zigflow validate workflow.yaml

Shell completion​

Zigflow generates completion scripts for common shells.

Bash​

source <(zigflow completion bash)

To make it persistent:

zigflow completion bash > /etc/bash_completion.d/zigflow

Zsh​

zigflow completion zsh > "${fpath[1]}/_zigflow"

Fish​

zigflow completion fish > ~/.config/fish/completions/zigflow.fish

Environment variables​

Every CLI flag can be set via an environment variable instead. The naming convention is: flag --flag-name becomes env var FLAG_NAME (uppercase, hyphens replaced by underscores).

Examples:

FlagEnv var
--temporal-addressTEMPORAL_ADDRESS
--temporal-api-keyTEMPORAL_API_KEY
--log-levelLOG_LEVEL
--disable-telemetryDISABLE_TELEMETRY

This applies to every flag in the CLI reference.

Useful flag combinations​

Connecting to Temporal Cloud​

zigflow run -f workflow.yaml \
  --temporal-address your-namespace.tmprl.cloud:7233 \
  --temporal-namespace your-namespace \
  --temporal-tls \
  --temporal-api-key your-api-key

Skipping validation on startup​

zigflow run -f workflow.yaml --validate=false

Use only when you have already validated separately.

Disabling telemetry​

zigflow run -f workflow.yaml --disable-telemetry

Changing the log level​

zigflow run -f workflow.yaml --log-level debug

Valid values: trace, debug, info, warn, error. See the CLI reference for the default.

Troubleshooting​

Worker starts but no executions run. The task queue and workflow type must match what your client uses. Check:

  • --task-queue in temporal workflow start matches document.taskQueue in your YAML
  • --type matches document.workflowType

"dial tcp: connection refused" on startup. Temporal is not reachable. Check --temporal-address and confirm the server is running.

Validation passes but the worker exits immediately. Run with --log-level debug to see what failed on startup.