Zigflow

https://zigflow.dev/docs
Admin
Zigflow is a declarative orchestration layer that enables developers to define workflows in YAML and...
Tokens:42,524
Snippets:636
Trust Score:4.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example CI Steps

Source: https://zigflow.dev/docs/guides/testing-workflows

Illustrates starting Temporal and Zigflow worker in the background for CI integration tests.

```bash
# Start Temporal in the background
temporal server start-dev &
  
# Start the Zigflow worker in the background
zigflow run -f workflow.yaml &
  
# Run test scripts
./scripts/run-integration-tests.sh
```

--------------------------------

### Example Workflow Execution Commands

Source: https://zigflow.dev/docs/dsl/debugging

Commands to run the complete CloudEvents debugging example. This includes starting the workflow worker, triggering the workflow, and watching HTTP logs.

```bash
cd examples/cloudevents  
  
# Start the workflow worker with CloudEvents enabled  
docker compose up workflow  
  
# In another terminal, trigger the workflow  
docker compose up trigger  
  
# Watch HTTP events  
docker compose logs -f http  

```

--------------------------------

### Install Zigflow with Go Install

Source: https://zigflow.dev/docs/getting-started/installation

Install the Zigflow binary using the Go package manager if you have Go installed. The binary will be placed in your `$GOPATH`.

```go
go install github.com/zigflow/zigflow@latest
```

--------------------------------

### Start Temporal Development Server

Source: https://zigflow.dev/docs/concepts/temporal-prereqs

Use the Temporal CLI to quickly start a local development server. This is useful for local development and testing.

```bash
temporal server start-dev
```

--------------------------------

### Basic Try/Catch Workflow Example

Source: https://zigflow.dev/docs/dsl/tasks/try

Demonstrates a workflow that attempts an HTTP GET request. If the request fails (e.g., due to a 404 error), it executes a catch block to set an error message.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: example
  version: 0.0.1
do:
  - user:
      try:
        - getUser:
            call: http
            output:
              as:
                user: ${ . }
            with:
              method: get
              # This URL returns a 404
              endpoint: https://jsonplaceholder.typicode.com/users/2000
      catch:
        do:
          - setError:
              output:
                as:
                  error: ${ . }
              set:
                message: some error

```

--------------------------------

### Install Zigflow with Homebrew

Source: https://zigflow.dev/docs/getting-started/installation

Use Homebrew to tap the Zigflow repository and install the Zigflow cask. This is a convenient method for macOS users.

```bash
brew tap zigflow/tap

brew install --cask zigflow
```

--------------------------------

### Start Temporal Development Server

Source: https://zigflow.dev/docs/examples/hello-world

Command to start a local Temporal development server, which is necessary for running Zigflow workflows.

```bash
temporal server start-dev

```

--------------------------------

### Expected Output Example

Source: https://zigflow.dev/docs/examples/http-call

This is an example of the expected JSON output from the `fetch-user` workflow, showing the structure of the user data retrieved.

```json
{
  "user": {
    "id": 1,
    "name": "Leanne Graham"
  }
}
```

--------------------------------

### Verify Zigflow Installation

Source: https://zigflow.dev/docs/getting-started/installation

After installation, run this command to check if Zigflow is installed correctly and to display its version.

```bash
zigflow version
```

--------------------------------

### Install Zigflow Helm Chart

Source: https://zigflow.dev/docs/deployment/kubernetes

Install the Zigflow Helm chart from the GitHub Container Registry OCI artifact. Replace `${ZIGFLOW_VERSION}` with the desired published version.

```bash
helm install zigflow oci://ghcr.io/zigflow/charts/zigflow@${ZIGFLOW_VERSION}
```

--------------------------------

### Basic Wait Task Example

Source: https://zigflow.dev/docs/dsl/tasks/wait

This example demonstrates how to configure a Wait task to pause a workflow for 5 seconds. Ensure the 'wait' property is set with a duration.

```yaml
document:  
  dsl: 1.0.0  
  taskQueue: zigflow  
  workflowType: example  
  version: 0.0.1  
do:  
  - wait:  
      wait:  
        seconds: 5  

```

--------------------------------

### Switch Task Example: Routing Orders

Source: https://zigflow.dev/docs/dsl/tasks/switch

This example demonstrates routing an order through different processing steps based on the 'orderType' input. Cases are evaluated in order, and the first matching 'when' expression determines the next task.

```yaml
document:  
  dsl: 1.0.0  
  taskQueue: zigflow  
  workflowType: order-router  
  version: 1.0.0  
do:  
  - routeOrder:  
      switch:  
        - electronic:  
            when: ${ $input.orderType == "electronic" }  
            then: processElectronicOrder  
        - physical:  
            when: ${ $input.orderType == "physical" }  
            then: processPhysicalOrder  
        - default:  
            then: handleUnknownType  
  
  - processElectronicOrder:  
      do:  
        - validatePayment:  
            call: http  
            with:  
              method: get  
              endpoint: https://jsonplaceholder.typicode.com/posts/1  
        - fulfillOrder:  
            call: http  
            with:  
              method: get  
              endpoint: https://jsonplaceholder.typicode.com/posts/2  
  
  - processPhysicalOrder:  
      do:  
        - checkInventory:  
            call: http  
            with:  
              method: get  
              endpoint: https://jsonplaceholder.typicode.com/posts/3  
  
  - handleUnknownType:  
      raise:  
        error:  
          type: https://serverlessworkflow.io/spec/1.0.0/errors/validation  
          status: 400  
          title: Unknown order type  
          detail: ${ "Received order type: " + $input.orderType }  
```

--------------------------------

### Trigger Workflow with Go SDK

Source: https://zigflow.dev/docs/getting-started/your-first-workflow

Example of triggering a Temporal workflow from Go application code. It connects to the Temporal server, starts the 'simple-workflow', and retrieves its result.

```go
package main

import (
  "context"
  "fmt"

  "go.temporal.io/sdk/client"
)

func main() {
  client, err := client.Dial(client.Options{})  
  if err != nil {
    panic(err)
  }
  defer client.Close()

  workflowOptions := client.StartWorkflowOptions{
    TaskQueue: "zigflow",
  }

  ctx := context.Background()
  workflowRun, err := client.ExecuteWorkflow(ctx, workflowOptions, "simple-workflow")
  if err != nil {
    panic(err)
  }

  var result any
  workflowRun.Get(ctx, &result)

  r, err := json.MarshalIndent(result, "", "  ")
  if err != nil {
    panic(err)
  }

  fmt.Println(string(r))
}
```

--------------------------------

### Go HTTP CloudEvents Receiver

Source: https://zigflow.dev/docs/dsl/debugging

Implement an HTTP receiver in Go to handle incoming CloudEvents. This example sets up a client, starts a receiver, and logs received event details.

```go
package main  
  
import (  
    "context"  
    "log"  

    cloudevents "github.com/cloudevents/sdk-go/v2"  
)  
  
func main() {  
    p, err := cloudevents.NewHTTP()  
    if err != nil {  
        log.Fatal(err)  
    }  

    c, err := cloudevents.NewClient(p)  
    if err != nil {  
        log.Fatal(err)  
    }  

    log.Fatal(c.StartReceiver(context.Background(), receive))  
}  
  
func receive(ctx context.Context, event cloudevents.Event) {  
    log.Printf("Received event %s of type %s from %s",  
        event.ID(),  
        event.Type(),  
        event.Source(),  
    )  

    var data map[string]any  
    if err := event.DataAs(&data); err == nil {  
        log.Printf("Data: %+v", data)  
    }  
}  

```

--------------------------------

### Example Workflow Output

Source: https://zigflow.dev/docs

This is the expected output from the 'simple-workflow' after it has been successfully executed.

```json
{
  "data": {
    "message": "Hello from Ziggy"
  }
}
```

--------------------------------

### Trigger Workflow with Ruby SDK

Source: https://zigflow.dev/docs/getting-started/your-first-workflow

Example of triggering a Temporal workflow from Ruby application code. It connects to the Temporal server and starts the 'simple-workflow'.

```ruby
require "temporalio/client"
require "json"

options = {
  target_host: 'localhost:7233',
  namespace: 'default'
}

# Connect to Temporal
client = Temporalio::Client.connect(
  options[:target_host],
  options[:namespace]
)

# Start workflow
handle = client.start_workflow(
  "simple-workflow",
  nil,
  task_queue: "zigflow",
  id: "mtls-workflow-#{Time.now.to_i}",
)

# Wait for result
result = handle.result

# Pretty-print JSON
puts JSON.pretty_generate(result)
```

--------------------------------

### Install Zigflow Helm Chart with Custom Values

Source: https://zigflow.dev/docs/deployment/kubernetes

Install the Zigflow Helm chart using a custom `values.yaml` file. This allows for more granular control over deployment settings.

```bash
helm install zigflow oci://ghcr.io/zigflow/charts/zigflow@${ZIGFLOW_VERSION} \
  -f values.yaml
```

--------------------------------

### Start Workflow Execution

Source: https://zigflow.dev/docs/examples/parallel-tasks

Command to manually start a workflow execution on the Temporal cluster. Specify the workflow type, task queue, and a unique workflow ID.

```bash
temporal workflow start \
  --type competing-tasks \
  --task-queue zigflow \
  --workflow-id race-1  

```

--------------------------------

### Minimal Kubernetes Deployment with Security Context and /tmp Volume

Source: https://zigflow.dev/docs/deployment/dedicated-image

A basic Kubernetes Deployment example incorporating the recommended security contexts and the /tmp volume mount for script execution.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-workflow
spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        fsGroup: 1000
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: zigflow
          image: your-registry/your-image:your-tag
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            capabilities:
              drop:
                - ALL
            seccompProfile:
              type: RuntimeDefault
          volumeMounts:
            - mountPath: /tmp
              name: tmp
      volumes:
        - name: tmp
          emptyDir:
            medium: Memory
            sizeLimit: 32Mi
```

--------------------------------

### Listen for Multiple Updates

Source: https://zigflow.dev/docs/dsl/tasks/listen

This example shows how to listen for multiple updates ('temperature' and 'bpm') and requires all of them to be received and satisfy specific conditions. The task progresses only after all specified updates are received and validated.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: updates
  version: 0.0.1
do:
  - callDoctor:
      metadata:
        timeout: 10s # Controls the AwaitWithTimeout timeout - defaults to 60s
      listen:
        to:
          # Only progress after every update received
          all:
            - with:
                # ID maps to the update name in Temporal
                id: temperature
                # Temporal update - used to make read/write request
                type: update
                acceptIf: ${ $data.temperature > 38 }
            - with:
                id: bpm
                type: update
                acceptIf: ${ $data.bpm < 60 or $data.bpm > 100 }
  - wait:
      output:
        as:
          temperature: ${ $data.temperature }
          bpm: ${ $data.bpm }
      wait:
        seconds: 10
```

--------------------------------

### Install Bash Completions for Linux

Source: https://zigflow.dev/docs/cli/commands/zigflow_completion_bash

Save the bash completion script to the /etc/bash_completion.d/ directory for persistent autocompletion on Linux. You will need to start a new shell session for this to take effect.

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

--------------------------------

### Start Workflow Execution

Source: https://zigflow.dev/docs/guides/testing-workflows

Initiate a workflow execution with a specific type, task queue, workflow ID, and input payload.

```bash
temporal workflow start \
  --type my-workflow \
  --task-queue zigflow \
  --workflow-id test-run-1 \
  --input '{"name": "test"}'
```

--------------------------------

### Run Zigflow MCP Server

Source: https://zigflow.dev/docs/cli/commands/zigflow_mcp

This command starts the Zigflow MCP server. Use flags to customize its behavior.

```bash
zigflow mcp [flags]
```

--------------------------------

### Raise Task Example

Source: https://zigflow.dev/docs/dsl/tasks/raise

This example demonstrates how to use the 'raise' task to fail a workflow explicitly with a structured error. It includes basic workflow definition and a 'raise' task with a specified error type and status.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: example
  version: 0.0.1
  metadata:
    activityOptions:
      startToCloseTimeout:
        minutes: 1
do:
  - wait:
      wait:
        seconds: 1
  - bug:
      raise:
        error:
          type: https://serverlessworkflow.io/spec/1.0.0/errors/communication
          status: 400

```

--------------------------------

### Comprehensive Set Task Example

Source: https://zigflow.dev/docs/dsl/tasks/set

Demonstrates setting various types of data, including primitives, environment variables, generated UUIDs, and nested objects/arrays, into the workflow state. It also shows how to override existing state values in subsequent Set tasks.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: example
  version: 0.0.1
do:
  - baseData:
      # Set the output to the context
      export:
        as: ${ . }
      set:
        # This value will be overidden later
        progress: 0
        # Set a variable from an envvar
        envvar: ${ $env.EXAMPLE_ENVVAR }
        # Generate a UUID
        uuid: ${ uuid }
        # Insert something from the input
        inputUserId: ${ $input.userId }
        # Maps can be used
        object:
          hello: world
          uuid: ${ uuid }
        # As can arrays
        array:
          - ${ uuid }
          - hello: world
  - updateProgress:
      # Merge this set with the context and output everything together
      output:
        as: ${ $context + . }
      set:
        # Overidden from above. Everything else remains the same
        progress: 100

```

--------------------------------

### Start Workflow Execution

Source: https://zigflow.dev/docs/examples/error-handling

This command triggers the execution of a specific Zigflow workflow in Temporal.

```bash
temporal workflow start \
  --type try-catch \
  --task-queue zigflow \
  --workflow-id catch-1
```

--------------------------------

### Example Workflow Definition

Source: https://zigflow.dev/docs/guides/testing-workflows

A sample Zigflow workflow definition that calls an HTTP endpoint.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: fetch-user
  version: 0.0.1
do:
  - fetchUser:
      call: http
      with:
        method: GET
        endpoint: https://api.example.com/users/1
```

--------------------------------

### Define a Zigflow Workflow in YAML

Source: https://zigflow.dev/docs/concepts/overview

Describe your workflow logic using YAML. This example defines a simple greeting workflow.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: greet-user
  version: 1.0.0
do:
  - greet:
      set:
        message: Hello from Ziggy
```

--------------------------------

### Competing Fork Example

Source: https://zigflow.dev/docs/dsl/tasks/fork

This example shows a Fork task configured in competing mode. Only the output from the fastest completing branch is returned, and all other branches are cancelled. Use this when you only need the result of the first successful operation.

```yaml
{

  "raiseAlarm": {

    // The workflow's data

  }

}

```

--------------------------------

### Non-competing Fork Example

Source: https://zigflow.dev/docs/dsl/tasks/fork

This example demonstrates the default behavior of the Fork task where all branches execute to completion and their outputs are collected. Use this when you need results from all parallel operations.

```yaml
document:  

  dsl: 1.0.0  

  taskQueue: zigflow  

  workflowType: example  

  version: 0.0.1  

do:  

  - raiseAlarm:  

      # A fork is a series of child workflows running in parallel  

      output:  

        # Add output to context without the `multiStep` key  

        as:  

          raiseAlarm: '${ $context + del(.multiStep) }'  

      fork:  

        # If not competing, all tasks will run to the finish - this is the default behaviour  

        compete: false  

        branches:  

          # A single step is passed in by the Serverless Workflow task  

          - callNurse:  

              call: http  

              with:  

                method: get  

                endpoint: https://jsonplaceholder.typicode.com/users/2  

          # Multiple steps can be passed in by the Serverless Workflow do task  

          - multiStep:  

              do:  

                - wait1:  

                    wait:  

                      seconds: 3  

                - wait2:  

                    wait:  

                      seconds: 2  

          # Another single step child workflow  

          - callDoctor:  

              call: http  

              with:  

                method: get  

                endpoint: ${ "https://jsonplaceholder.typicode.com/users/" + ($input.userId | tostring) }  

  

```

--------------------------------

### Trigger a workflow execution using Temporal CLI

Source: https://zigflow.dev/docs/getting-started/quickstart

Start an instance of the 'hello-world' workflow using the Temporal CLI. This command specifies the workflow type, task queue, and a unique workflow ID.

```bash
temporal workflow start \
  --type hello-world \
  --task-queue zigflow \
  --workflow-id my-first-workflow
```

--------------------------------

### Start Workflow Execution

Source: https://zigflow.dev/docs/examples/signal-driven

Initiate a new workflow execution of type 'signal' on the 'zigflow' task queue. A unique workflow ID is assigned for tracking.

```bash
temporal workflow start \
  --type signal \
  --task-queue zigflow \
  --workflow-id approval-1
```

--------------------------------

### Install Zsh Completions Persistently on Linux

Source: https://zigflow.dev/docs/cli/commands/zigflow_completion_zsh

Redirect the output of 'zigflow completion zsh' to a file in your fpath for persistent autocompletion on Linux. This command should be executed once.

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

--------------------------------

### Trigger Workflow Execution with Temporal CLI

Source: https://zigflow.dev/docs/cli/using-the-cli

Use the Temporal CLI to start workflow executions. Pass input using the --input flag.

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

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

--------------------------------

### Start Zigflow Workflow Workers

Source: https://zigflow.dev/docs/cli/commands/zigflow_run

Use this command to start one or more Zigflow workflow workers. Workers connect to Temporal and process workflow executions defined in the provided workflow definitions. Definitions can be loaded from files or directories.

```bash
zigflow run [flags]
```

--------------------------------

### Try/Catch Workflow Example

Source: https://zigflow.dev/docs/examples/error-handling

This workflow demonstrates how to use a try/catch block to handle an HTTP call that is expected to fail. The 'catch' block intercepts the error and sets a fallback value.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: try-catch
  version: 0.0.1
do:
  - user:
      try:
        - getUser:
            call: http
            with:
              method: get
              endpoint: https://jsonplaceholder.typicode.com/users/2000
      catch:
        do:
          - setError:
              set:
                err: some error
```

--------------------------------

### Example CloudEvents Output Structure

Source: https://zigflow.dev/docs/dsl/debugging

This shows the directory structure and file names for captured CloudEvents after a workflow runs. Each YAML file contains a sequence of CloudEvents.

```yaml
./tmp/events/  

├── 550e8400-e29b-41d4-a716-446655440000.yaml  

└── 550e8400-e29b-41d4-a716-446655440001.yaml  
```

--------------------------------

### Listen for Query Event

Source: https://zigflow.dev/docs/dsl/tasks/listen

This example demonstrates how a workflow can listen for a 'query' event to retrieve its current state. The 'id' property maps to the query name in Temporal, and the 'data' payload is returned as-is. The workflow progresses through creating, updating, and finishing states while responding to queries.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: query
  version: 0.0.1
do:
  - queryState:
      listen:
        to:
          one:
            with:
              # ID maps to the query name in Temporal
              id: get_state
              type: query
              # This data will be returned as-is
              data:
                id: ${ $data.id }
                progress: ${ $data.progressPercentage }
                status: ${ $data.status }
  - createState:
      output:
        as:
          data: ${ . }
      set:
        id: ${ uuid }
        status: not started
        progress: 0
  - wait:
      wait:
        seconds: 5
  - updateState:
      set:
        progress: 50
        status: running
  - wait:
      wait:
        seconds: 5
  - updateState:
      set:
        progress: 100
        status: finished
```

--------------------------------

### File Protocol Configuration Example

Source: https://zigflow.dev/docs/dsl/debugging

Configure the file protocol to write CloudEvents to YAML files on disk. Events are appended to files organized by workflow execution ID, with each workflow creating a separate file named `<workflowID>.yaml`.

```yaml
clients:  
  - name: file-logger  
    protocol: file  
    target: "./tmp/events"  

```

--------------------------------

### Example Workflow Definition

Source: https://zigflow.dev/docs/dsl/tasks/run

Defines a parent workflow that sequentially calls two child workflows after initial waits. Each child workflow also has its own defined execution steps.

```yaml
document:  
  dsl: 1.0.0  
  taskQueue: zigflow  
  workflowType: example  
  version: 0.0.1  
  metadata:  
    activityOptions:  
      startToCloseTimeout:  
        minutes: 1  
do:  
  - parentWorkflow:  
      do:  
        - wait:  
            wait:  
              seconds: 5  
        - callChildWorkflow1:  
            run:  
              workflow:  
                type: child-workflow1  
        - wait:  
            wait:  
              seconds: 5  
        - callChildWorkflow2:  
            run:  
              workflow:  
                type: child-workflow2  
  - child-workflow1:  
      do:  
        - wait:  
            wait:  
              seconds: 10  
  - child-workflow2:  
      do:  
        - wait:  
            wait:  
              seconds: 3  
```

--------------------------------

### Minimal Zigflow Workflow Example

Source: https://zigflow.dev/docs/concepts/durable-execution-in-yaml

This YAML defines a simple workflow with three sequential HTTP tasks: validateOrder, chargeCard, and notifyUser. Each task is executed as a Temporal activity.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: charge-customer
  version: 1.0.0
do:
  - validateOrder:
      call: http
      with:
        method: post
        endpoint: https://api.example.com/orders/validate
  - chargeCard:
      call: http
      with:
        method: post
        endpoint: https://api.example.com/payments
  - notifyUser:
      call: http
      with:
        method: post
        endpoint: https://api.example.com/notifications
```

--------------------------------

### Trigger Workflow with Python SDK

Source: https://zigflow.dev/docs/getting-started/your-first-workflow

Example of triggering a Temporal workflow from Python application code. It connects to the Temporal server and executes the 'simple-workflow'.

```python
import asyncio
import json

from temporalio.client import Client

async def main():
    client = await Client.connect("localhost:7233")

    result = await client.execute_workflow(
        "simple-workflow",
        id="your-workflow-id",
        task_queue="zigflow",
    )

    print(json.dumps(result, indent=2))


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Configure Workflow Schedule with CRON

Source: https://zigflow.dev/docs/dsl/intro

Schedule a workflow to run at a specific time using a CRON expression. This example sets a daily schedule at midnight.

```yaml
cron: 0 0 * * *
```

--------------------------------

### Install Bash Completions for macOS

Source: https://zigflow.dev/docs/cli/commands/zigflow_completion_bash

Save the bash completion script to the appropriate directory for Homebrew-managed bash completions on macOS. A new shell session is required for the changes to apply.

```bash
zigflow completion bash > $(brew --prefix)/etc/bash_completion.d/zigflow
```

--------------------------------

### Install Zsh Completions Persistently on macOS

Source: https://zigflow.dev/docs/cli/commands/zigflow_completion_zsh

Redirect the output of 'zigflow completion zsh' to the appropriate directory for persistent autocompletion on macOS using Homebrew. A new shell session is required for this to take effect.

```zsh
zigflow completion zsh > $(brew --prefix)/share/zsh/site-functions/_zigflow
```

--------------------------------

### Workflow Validation Failure Example

Source: https://zigflow.dev/docs/dsl/debugging

An example of a validation error message when starting a Zigflow worker. It indicates a missing required field, `workflowType`, and suggests running `zigflow validate`.

```text
❌ Validation failed for workflow.yaml  
  
1 validation error(s):  
  
1. document.workflowType: is required  

```

--------------------------------

### Zigflow Completion Help Options

Source: https://zigflow.dev/docs/cli/commands/zigflow_completion

Displays the help options for the zigflow completion command.

```bash
  -h, --help   help for completion  
```

--------------------------------

### Trigger Workflow with TypeScript SDK

Source: https://zigflow.dev/docs/getting-started/your-first-workflow

Example of triggering a Temporal workflow from TypeScript application code. It establishes a connection and starts the 'simple-workflow' using the client.

```typescript
import { Connection, Client } from '@temporalio/client';
import { nanoid } from 'nanoid';

async function bootstrap() {
  const connection = await Connection.connect();

  const client = new Client({
    connection,
  });

  const handle = await client.workflow.start('simple-workflow', {
    taskQueue: 'zigflow',
    workflowId: nanoid(),
  });

  console.log(JSON.stringify(await handle.result(), null, '  '));
}

bootstrap().catch((err) => {
  console.error(err);
  process.exit(1);
});
```

--------------------------------

### Zigflow Version Command Options

Source: https://zigflow.dev/docs/cli/commands/zigflow_version

Displays help information for the version command.

```bash
-h, --help   help for version
```

--------------------------------

### Basic Docker Usage

Source: https://zigflow.dev/docs/deployment/docker

Mount your workflow file into the container and specify its path using the -f flag. Use 'host.docker.internal' to connect to a Temporal server on your host machine. On Linux, '172.17.0.1' or '--network host' might be necessary.

```bash
docker run --rm \
  -v /path/to/workflow.yaml:/app/workflow.yaml \
  ghcr.io/zigflow/zigflow \
  run -f /app/workflow.yaml \
  --temporal-address host.docker.internal:7233
```

--------------------------------

### Define a simple 'hello-world' workflow

Source: https://zigflow.dev/docs/getting-started/quickstart

This YAML file defines a basic workflow named 'hello-world' that sets a message and outputs it. It specifies the task queue and workflow version.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: hello-world
  version: 1.0.0
do:
  - greet:
      set:
        message: Hello from Ziggy
      output:
        as:
          data: ${ . }
```

--------------------------------

### Build Zigflow from Source

Source: https://zigflow.dev/docs/getting-started/installation

Clone the Zigflow repository and build the binary from source. This is useful for testing unreleased versions or contributing to the project.

```bash
git clone https://github.com/zigflow/zigflow.git

cd zigflow

go build .
```

--------------------------------

### Basic HTTP GET Request

Source: https://zigflow.dev/docs/examples/http-call

Use `call: http` to make a GET request to an external API and map the response body to workflow state. Ensure the worker has network access to the endpoint.

```yaml
document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: fetch-user
  version: 0.0.1
do:
  - getUser:
      call: http
      output:
        as:
          user: ${ . }
      with:
        method: get
        endpoint: https://jsonplaceholder.typicode.com/users/1
```

--------------------------------

### Embed workflow path in start marker

Source: https://zigflow.dev/docs/cli/commands/zigflow_graph_inject

Embed the workflow file path directly within the start marker comment in your target file. This allows for automatic detection by the zigflow graph inject command.

```html
<!-- ZIGFLOW_GRAPH_START ./workflow.yaml -->  

<!-- ZIGFLOW_GRAPH_END -->  
```

--------------------------------

### Zigflow CLI SEE ALSO Section

Source: https://zigflow.dev/docs/cli/commands/zigflow

Lists available subcommands for the Zigflow CLI, including commands for completion, graph generation, running workflows, schema output, validation, and version display.

```bash
zigflow completion - Generate the autocompletion script for the specified shell
zigflow graph - Generate a visual graph of a Zigflow workflow
zigflow mcp - Run the Zigflow MCP server
zigflow run - Start Zigflow workflow workers
zigflow schema - Output the Zigflow JSON schema. 
zigflow validate - Validate a Zigflow workflow file
zigflow version - Displays version information
```

--------------------------------

### Run Go Application

Source: https://zigflow.dev/docs/getting-started/your-first-workflow

Command to execute the Go application that triggers the Temporal workflow.

```bash
go run .
```

--------------------------------

### View Workflow Result

Source: https://zigflow.dev/docs/examples/hello-world

Command to display the result of a previously started workflow execution using its workflow ID.

```bash
temporal workflow show --workflow-id hello-1

```

--------------------------------

### MCP Command Options

Source: https://zigflow.dev/docs/cli/commands/zigflow_mcp

Provides help for the mcp command itself.

```bash
  -h, --help   help for mcp  
```

--------------------------------

### Validate Zigflow Workflow

Source: https://zigflow.dev/docs/concepts/how-zigflow-runs

Validate a Zigflow workflow definition without starting the worker. This checks for schema compliance and syntax errors.

```bash
zigflow validate workflow.yaml
```

--------------------------------

### Run Zigflow Worker

Source: https://zigflow.dev/docs/examples/hello-world

Command to start the Zigflow worker, which connects to the Temporal server and executes workflows defined in the specified YAML file.

```bash
zigflow run -f workflow.yaml

```

--------------------------------

### Run Zigflow with File Mode

Source: https://zigflow.dev/docs/deployment/docker

Use this command to load a single workflow definition file. Ensure the volume mount path matches the WORKFLOW_FILE environment variable.

```docker
docker run --rm \
  -v /path/to/workflow.yaml:/app/workflow.yaml \
  -e WORKFLOW_FILE=/app/workflow.yaml \
  ghcr.io/zigflow/zigflow run
```

--------------------------------

### Enable CloudEvents using CLI or Environment Variable

Source: https://zigflow.dev/docs/dsl/debugging

Configure CloudEvents emission by providing a configuration file path using either the CLI flag `--cloudevents-config` or the environment variable `CLOUDVENTS_CONFIG`.

```bash
# Using CLI flag  

zigflow run --cloudevents-config ./cloudevents.yaml  

# Using environment variable  

export CLOUDVENTS_CONFIG=./cloudevents.yaml  
zigflow run  

```

--------------------------------

### Configure Temporal Cloud Connection with API Key

Source: https://zigflow.dev/docs/deployment/docker

Connect to Temporal Cloud using an API key. Ensure TEMPORAL_TLS is set to "true" and provide your namespace and API key.

```yaml
environment:
  TEMPORAL_ADDRESS: your-namespace.tmprl.cloud:7233
  TEMPORAL_NAMESPACE: your-namespace
  TEMPORAL_TLS: "true"
  TEMPORAL_API_KEY: your-api-key
```

--------------------------------

### Run Zigflow Worker

Source: https://zigflow.dev/docs/examples/parallel-tasks

Command to start the Zigflow worker, which will poll the specified task queue for workflows to execute. Ensure the workflow definition file is provided.

```bash
zigflow run -f workflow.yaml  

```

--------------------------------

### Default markers for injection

Source: https://zigflow.dev/docs/cli/commands/zigflow_graph_inject

These are the default marker comments used by zigflow to identify the section where the graph should be injected. The start marker can optionally contain a workflow path.

```html
<!-- ZIGFLOW_GRAPH_START -->  

<!-- ZIGFLOW_GRAPH_END -->  
```

--------------------------------

### Environment Variables for Workflows

Source: https://zigflow.dev/docs/deployment/kubernetes

Configure environment variables to be passed to workflows. By default, variables are prefixed with `ZIGGY_`. This example shows how to set a custom base URL.

```yaml
envvars:
  - name: ZIGGY_API_BASE_URL
    value: https://api.example.com
```

--------------------------------

### Configure TWC Connection (No Authentication)

Source: https://zigflow.dev/docs/deployment/kubernetes

Set up the Temporal Connection for TWC when Temporal is running within the same cluster and does not require authentication.

```yaml
controller:
  connection:
    hostPort: temporal.temporal.svc.cluster.local:7233
```

--------------------------------

### Run Docker Container

Source: https://zigflow.dev/docs/dsl/tasks/run

Executes a Docker container with specified image, arguments, and environment variables. Ensure the 'docker' binary is available on your local machine.

```yaml
document:  
  dsl: 1.0.0  
  taskQueue: zigflow  
  workflowType: example  
  version: 0.0.1  
do:  
  - container:  
      run:  
        container:  
          image: alpine  
          arguments:  
            - env  
          environment:  
            hello: world  
```

--------------------------------

### Docker Compose Setup for Temporal and Zigflow

Source: https://zigflow.dev/docs/deployment/docker

A typical Docker Compose configuration to run Temporal and Zigflow together. The worker depends on the Temporal service being healthy.

```yaml
services:
  temporal:
    image: temporalio/temporal
    command: server start-dev --ip 0.0.0.0
    ports:
      - "8233:8233"
      - "7233:7233"
    healthcheck:
      test: ["CMD-SHELL", "temporal operator cluster health"]
      interval: 10s
      timeout: 10s
      retries: 3
  
  worker:
    image: ghcr.io/zigflow/zigflow
    command:
      - run
      - -f
      - /app/workflow.yaml
    environment:
      TEMPORAL_ADDRESS: temporal:7233
      TEMPORAL_NAMESPACE: default
      LOG_LEVEL: info
    volumes:
      - ./workflow.yaml:/app/workflow.yaml
    depends_on:
      temporal:
        condition: service_healthy
```

--------------------------------

### Run Zigflow using Docker

Source: https://zigflow.dev/docs/getting-started/installation

Execute Zigflow from its official Docker image. Mount your workflow file into the container and specify the 'run' command.

```bash
docker run -it --rm \
  -v /path/to/workflow.yaml:/app/workflow.yaml \
  ghcr.io/zigflow/zigflow \
  run
```

--------------------------------

### Trigger Zigflow Workflow

Source: https://zigflow.dev/docs/examples/hello-world

Command to start a specific workflow execution on the Temporal server. Ensure the --type and --task-queue values match the workflow definition.

```bash
temporal workflow start \
  --type hello-world \
  --task-queue zigflow \
  --workflow-id hello-1

```

--------------------------------

### Load Bash Completions for Current Session

Source: https://zigflow.dev/docs/cli/commands/zigflow_completion_bash

Source the output of the zigflow completion bash command to enable autocompletion in your current shell session. This requires the 'bash-completion' package to be installed.

```bash
source <(zigflow completion bash)
```

--------------------------------

### Example CloudEvent Payload

Source: https://zigflow.dev/docs/dsl/debugging

This illustrates the content of a CloudEvent file, formatted in YAML. It includes event metadata like specversion, type, source, id, time, datacontenttype, and the event data.

```yaml
---
specversion: "1.0"
type: dev.zigflow.workflow.started
source: zigflow.dev/zigflow/example
id: 550e8400-e29b-41d4-a716-446655440000
time: "2026-02-09T10:30:00Z"
datacontenttype: application/json
data:
  workflowType: example
  input:
    userId: 42
---
specversion: "1.0"
type: dev.zigflow.task.started
source: zigflow.dev/zigflow/example
id: 550e8400-e29b-41d4-a716-446655440001
time: "2026-02-09T10:30:01Z"
datacontenttype: application/json
data:
  taskName: getUser
  context:
    userId: 42

```

--------------------------------

### Inspect Zigflow Image SBOM with Cosign

Source: https://zigflow.dev/docs/deployment/dedicated-image

Download and inspect the CycloneDX SBOM attached to the Zigflow image reference using Cosign. This provides details about the image's components.

```bash
cosign download sbom ghcr.io/zigflow/zigflow:$VERSION
```

--------------------------------

### Run the MCP Server

Source: https://zigflow.dev/docs/cli/mcp-server

The Zigflow MCP server is designed to be launched and managed by an MCP-compatible client via stdin/stdout. It is not intended for interactive terminal use.

```bash
zigflow mcp  
```

--------------------------------

### Zigflow HTTP Client Configuration

Source: https://zigflow.dev/docs/dsl/debugging

Configure an HTTP client in Zigflow to send CloudEvents to a specified target endpoint. This example shows settings for name, protocol, target URL, and HTTP method.

```yaml
clients:
  - name: debug-server
    protocol: http
    target: "http://localhost:8080"
    options:
      timeout: 10s
      method: POST

```

--------------------------------

### Build Docker Image

Source: https://zigflow.dev/docs/deployment/dedicated-image

Command to build the Docker image with the embedded workflow. Replace 'your-registry/your-image:your-tag' with your desired image name and tag.

```bash
docker build -t your-registry/your-image:your-tag .
```

--------------------------------

### Connect to Temporal Cloud

Source: https://zigflow.dev/docs/cli/using-the-cli

Run a Zigflow worker and connect to Temporal Cloud using specific flags for address, namespace, TLS, and API key.

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

--------------------------------

### Zigflow Schema Command Options

Source: https://zigflow.dev/docs/cli/commands/zigflow_schema

Configures the output format and help for the 'zigflow schema' command. The output can be JSON or YAML.

```bash
  -h, --help            help for schema  

  -o, --output string   Output format. One of: (json, yaml) (default "json")
```

--------------------------------

### Inject command options

Source: https://zigflow.dev/docs/cli/commands/zigflow_graph_inject

These options allow customization of the zigflow graph inject command, including setting custom start and end markers, specifying the output format, and providing an explicit workflow file.

```bash
  -e, --end-marker string     End marker comment (default "<!-- ZIGFLOW_GRAPH_END -->")  
  -h, --help                  help for inject  
  -o, --output string         Output format (mermaid) (default "mermaid")  
  -s, --start-marker string   Start marker comment (requires --workflow) (default "<!-- ZIGFLOW_GRAPH_START -->")  
  -w, --workflow string       Explicit workflow file (auto-detected from start marker if not set)  
```

--------------------------------

### Zigflow Version Command Synopsis

Source: https://zigflow.dev/docs/cli/commands/zigflow_version

Prints version information for the Zigflow CLI. The output includes the version number and Git commit hash.

```bash
zigflow version [flags]
```

--------------------------------

### Auto-detect workflow file path

Source: https://zigflow.dev/docs/cli/commands/zigflow_graph_inject

Use this command when the workflow file path is embedded within the start marker comment in the target file. If no path is found, it defaults to 'workflow.yaml' relative to the target file.

```bash
zigflow graph inject <target-file> [target-file...]  
```
Tokens:
Raw