home / skills / windmill-labs / windmill / write-script-bash

write-script-bash skill

safe

/system_prompts/auto-generated/skills/write-script-bash

This skill helps you write Bash scripts with positional arguments, JSON output, and Windmill integration for automation and deployment.

npx playbooks add skill windmill-labs/windmill --skill write-script-bash

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.1 KB

---
name: write-script-bash
description: MUST use when writing Bash scripts.
---

## CLI Commands

Place scripts in a folder. After writing, run:
- `wmill script generate-metadata` - Generate .script.yaml and .lock files
- `wmill sync push` - Deploy to Windmill

Use `wmill resource-type list --schema` to discover available resource types.

# Bash

## Structure

Do not include `#!/bin/bash`. Arguments are obtained as positional parameters:

```bash
# Get arguments
var1="$1"
var2="$2"

echo "Processing $var1 and $var2"

# Return JSON by echoing to stdout
echo "{\"result\": \"$var1\", \"count\": $var2}"
```

**Important:**
- Do not include shebang (`#!/bin/bash`)
- Arguments are always strings
- Access with `$1`, `$2`, etc.

## Output

The script output is captured as the result. For structured data, output valid JSON:

```bash
name="$1"
count="$2"

# Output JSON result
cat << EOF
{
  "name": "$name",
  "count": $count,
  "timestamp": "$(date -Iseconds)"
}
EOF
```

## Environment Variables

Environment variables set in Windmill are available:

```bash
# Access environment variable
echo "Workspace: $WM_WORKSPACE"
echo "Job ID: $WM_JOB_ID"
```

Overview

This skill guides writing Bash scripts for Windmill-style workflows and webhooks. It focuses on the conventions required to run scripts inside the platform, including argument handling, environment access, and JSON output. It also lists the CLI commands to generate metadata and deploy scripts.

How this skill works

The skill enforces writing Bash scripts without a shebang and using positional parameters ($1, $2, ...) since all arguments arrive as strings. It requires scripts to emit their result on stdout, preferably as valid JSON for structured data. The skill also explains how to access environment variables provisioned by the platform and the CLI commands to generate metadata and push deployments.

When to use it

When creating Bash steps for Windmill workflows or webhooks
When you need scripts to return structured results to the workflow engine
When you want to access workspace or job environment variables inside scripts
When preparing scripts for deployment via the Windmill CLI
When converting existing scripts to be platform-compatible

Best practices

Do not include a shebang (#!/bin/bash) — the runtime supplies the shell
Treat all inputs as strings and read them via positional parameters ($1, $2, ...). Validate/convert as needed
Return results by echoing or using a heredoc to emit valid JSON on stdout
Use environment variables like WM_WORKSPACE and WM_JOB_ID for contextual info rather than hardcoding values
Run wmill script generate-metadata before deploying, and use wmill sync push to deploy changes
Use wmill resource-type list --schema to discover available resource types and their schemas

Example use cases

A script that accepts a username and retry count, performs an API call, and returns a JSON status object
A scheduled task that reads workspace ID from WM_WORKSPACE and outputs a run summary JSON
A webhook handler that parses two positional arguments and returns structured data used by downstream steps
A migration helper that reads credentials from platform environment variables and prints a JSON report
A lightweight ETL step that takes a table name and row limit, queries a database resource, and emits fetched rows as JSON

FAQ

Why must I omit the shebang?

The platform launches scripts in a managed shell environment; adding a shebang can conflict with the runtime and is therefore disallowed.

How should I return complex results?

Serialize your output as valid JSON and write it to stdout. Use heredocs or echo to produce well-formed JSON including timestamps and numeric values.