Script Variables

Overview

Script variables let you write reusable markdown scripts with customizable parameters. Users can override variables from the command line without editing the script itself.

YAML Front-Matter Syntax

Declare variables in a YAML front-matter block at the top of your script:

#!/usr/bin/env -S ai --haiku
---
vars:
  topic: "machine learning"
  style: casual
  audience:
---
Write a summary of {{topic}} in {{style}} style.
Target audience: {{audience}}.

Syntax Rules

Opt-in: Variables only activate when front-matter contains vars:. No vars: = no behavior change.
Front-matter stripped: The --- block is removed from the prompt when vars: is present.
Default values: Variables can have default values (like topic: "machine learning")
No default: Variables declared with just the key (like audience:) have no default value

Placeholder Substitution

Use {{varname}} syntax to insert variable values into your prompt:

Write a {{length}} summary of {{topic}} in a {{style}} tone.

The {{placeholder}} syntax:

Doesn’t collide with shell variables ($VAR)
Doesn’t collide with markdown syntax
Doesn’t collide with Claude syntax
Is visually distinct and easy to read

Unset Variables

A variable declared with no default (just key:) and no CLI override leaves {{key}} as-is in the prompt:

---
vars:
  topic:
---
Summarize {{topic}}.

Without --topic flag: “Summarize .” (literal text) With --topic "AI": “Summarize AI.”

CLI Overrides

Override variables from the command line using flag syntax:

./script.md --varname value
./script.md --varname="value with spaces"
./script.md --varname                      # boolean — sets to "true"

Hyphens in flag names are normalized to underscores when matching variables. --my-var matches my_var, so you can use natural CLI conventions:

./script.md --brief-only                   # matches vars: brief_only
./script.md --max-retries 5                # matches vars: max_retries
./script.md --output-dir="/tmp/results"    # matches vars: output_dir

Examples

Given this script:

summarize-topic.md

#!/usr/bin/env -S ai --haiku
---
vars:
  topic: "machine learning"
  style: casual
  length: short
---
Write a {{length}} summary of {{topic}} in a {{style}} tone.

Run with defaults:

./summarize-topic.md
# Uses: topic="machine learning", style=casual, length=short

Override one variable:

./summarize-topic.md --topic "AI safety"
# Uses: topic="AI safety", style=casual, length=short

Override multiple variables:

./summarize-topic.md --topic "AI safety" --style formal
# Uses: topic="AI safety", style=formal, length=short

Equals form works too:

./summarize-topic.md --topic="robotics" --length="100 words"

Boolean flag (no value — sets to "true"):

./summarize-topic.md --verbose
# Sets verbose to "true" if declared in vars

Mixing with AI Runner Flags

Variable overrides mix freely with AI Runner flags and provider overrides:

# --live is an AI Runner flag, --topic is a variable override
./summarize-topic.md --live --topic "quantum computing"

# Override provider + model alongside variables
ai --aws --opus summarize-topic.md --topic "the fall of rome"

# All together
./summarize-topic.md --live --length "100 words" --topic "the fall of rome" --style "peter griffin"

How Flag Consumption Works

Override flags matching declared var names are consumed by the variable system — they don’t pass through to Claude Code:

--topic, --style, --length are consumed (match declared vars)
--live, --aws, --opus pass through to AI Runner
Unrecognized flags (like --verbose) pass through to Claude Code

Complete Example

Here’s a real-world script with variables:

summarize-topic.md

#!/usr/bin/env -S ai --haiku
---
vars:
  topic: "machine learning"
  style: casual
  length: short
---
Write a {{length}} summary of {{topic}} in a {{style}} tone.

Usage Examples

Default behavior:

./summarize-topic.md

Output: Short, casual summary of machine learning Override topic:

./summarize-topic.md --topic "quantum computing"

Output: Short, casual summary of quantum computing Override all variables:

./summarize-topic.md \
  --topic "the fall of rome" \
  --style "peter griffin" \
  --length "100 words"

Output: 100-word summary of the fall of Rome in Peter Griffin’s style With live streaming:

./summarize-topic.md --live --topic "AI safety"

Output: Streams the summary in real-time With provider override:

ai --aws --opus summarize-topic.md --topic "climate change" --style formal

Uses AWS Bedrock with Claude Opus, formal style summary of climate change

Advanced Patterns

Optional vs Required Variables

Optional (with default):

---
vars:
  format: markdown
  verbose: false
---
Generate output in {{format}} format. Verbose mode: {{verbose}}.

Toggle a boolean variable from the CLI:

./script.md --verbose         # sets verbose to "true"
./script.md                   # uses default "false"

Required (no default):

---
vars:
  target_file:
  operation:
---
Perform {{operation}} on {{target_file}}.

Users must provide --target-file and --operation (or --target_file — both work) or the placeholders remain literal.

Multiple Scripts with Shared Variables

Create a family of scripts that accept the same variables:

analyze.md

---
vars:
  language: python
  depth: basic
---
Analyze {{language}} code with {{depth}} depth.

review.md

---
vars:
  language: python
  depth: basic
---
Review {{language}} code for {{depth}} issues.

Both scripts accept the same flags:

./analyze.md --language go --depth thorough
./review.md --language go --depth thorough

Pipeline with Variables

Pass variables through a pipeline:

./extract.md --source data.json | \
./transform.md --format csv | \
./validate.md --schema schema.json > output.csv

Each script in the pipeline can have its own variables.

Common Use Cases

1. Documentation Generator

generate-docs.md

#!/usr/bin/env -S ai --skip
---
vars:
  source_dir: src
  output_file: ARCHITECTURE.md
  style: technical
---
Read files in {{source_dir}}/
Generate {{output_file}} documenting the codebase.
Use {{style}} writing style.

Usage:

./generate-docs.md
./generate-docs.md --source_dir lib --output_file README.md --style casual

2. Test Runner

run-tests.md

#!/usr/bin/env -S ai --skip
---
vars:
  test_pattern: "*.test.js"
  framework: jest
  coverage: false
---
Run tests matching {{test_pattern}} using {{framework}}.
Generate coverage report: {{coverage}}.

Usage:

./run-tests.md
./run-tests.md --test_pattern "integration/*.test.ts" --coverage true

3. Code Reviewer

review.md

#!/usr/bin/env -S ai --opus
---
vars:
  focus: security
  severity: high
  output_format: markdown
---
Review code for {{focus}} issues.
Only report {{severity}} severity and above.
Output in {{output_format}} format.

Usage:

./review.md
./review.md --focus performance --severity medium --output_format json

4. Data Analyzer

analyze-data.md

#!/usr/bin/env ai
---
vars:
  metric: revenue
  period: monthly
  visualization: false
---
Analyze {{metric}} trends over {{period}} periods.
Include visualization: {{visualization}}.

Usage:

cat data.csv | ./analyze-data.md --metric users --period weekly

Best Practices

Do:

Provide sensible defaults for optional parameters
Use descriptive variable names (source_dir not src)
Document expected values in comments
Keep variable names lowercase with underscores (users can override with hyphens: --my-var matches my_var)
Use boolean variables for feature flags (verbose: false) — users toggle with --verbose

Don’t:

Use variable names that match Claude Code flags — they’ll shadow the flag (prefix with your domain, e.g., report_format not format; check claude --help if unsure)
Put sensitive data in default values (use environment variables instead)
Create too many variables (makes scripts hard to use)
Use complex variable names (target_file_for_processing → target_file)

Troubleshooting

Variables Not Substituting

Problem: {{topic}} appears literally in output Solutions:

Check YAML syntax (must have vars: key)
Ensure front-matter is at the top of the file
Verify closing --- after front-matter
Check variable is declared in vars: block

CLI Override Not Working

Problem: --topic "AI" doesn’t override the default Solutions:

Check variable is declared in front-matter
Verify flag syntax: --topic value, --topic="value", or --topic (boolean)
Check for typos in variable name — hyphens and underscores are interchangeable (--my-var and --my_var both match my_var)
Ensure flag comes after script name: ./script.md --topic "AI"

Boolean vs value flags: --varname without a following value sets the variable to "true". If you intended to pass a value, make sure it follows the flag: --topic "AI" not just --topic. For values starting with --, use equals form: --topic="--special".

Conflicts with Claude Code Flags

Problem: --format json is interpreted as a variable instead of a Claude Code flag Solution: Variable names that match Claude Code flags will shadow them — the variable system consumes the flag before Claude Code sees it. To avoid conflicts:

Prefix variable names with your script’s domain (e.g., report_format instead of format)
Check claude --help if unsure whether a name conflicts
AI Runner flags (--live, --quiet, --aws, --model, etc.) are consumed before variable matching, so they can’t conflict
Short flags (-c, -n, -p) also can’t conflict — variable matching only checks -- double-dash form

Next Steps

Writing Scripts

Learn script basics and common patterns

Live Output

Stream progress in real-time

CI/CD Automation

Use variables in CI/CD pipelines

Permissions

Control what scripts can do

Get Started

Core Concepts

Guides

Providers

Advanced

Overview

YAML Front-Matter Syntax

Syntax Rules

Placeholder Substitution

Unset Variables

CLI Overrides

Examples

Mixing with AI Runner Flags

How Flag Consumption Works

Complete Example

Usage Examples

Advanced Patterns

Optional vs Required Variables

Multiple Scripts with Shared Variables

Pipeline with Variables

Common Use Cases

1. Documentation Generator

2. Test Runner

3. Code Reviewer

4. Data Analyzer

Best Practices

Troubleshooting

Variables Not Substituting

CLI Override Not Working

Conflicts with Claude Code Flags

Next Steps

Writing Scripts

Live Output

CI/CD Automation

Permissions

​Overview

​YAML Front-Matter Syntax

​Syntax Rules

​Placeholder Substitution

​Unset Variables

​CLI Overrides

​Examples

​Mixing with AI Runner Flags

​How Flag Consumption Works

​Complete Example

​Usage Examples

​Advanced Patterns

​Optional vs Required Variables

​Multiple Scripts with Shared Variables

​Pipeline with Variables

​Common Use Cases

​1. Documentation Generator

​2. Test Runner

​3. Code Reviewer

​4. Data Analyzer

​Best Practices

​Troubleshooting

​Variables Not Substituting

​CLI Override Not Working

​Conflicts with Claude Code Flags

​Next Steps

Writing Scripts

Live Output

CI/CD Automation

Permissions

Overview

YAML Front-Matter Syntax

Syntax Rules

Placeholder Substitution

Unset Variables

CLI Overrides

Examples

Mixing with AI Runner Flags

How Flag Consumption Works

Complete Example

Usage Examples

Advanced Patterns

Optional vs Required Variables

Multiple Scripts with Shared Variables

Pipeline with Variables

Common Use Cases

1. Documentation Generator

2. Test Runner

3. Code Reviewer

4. Data Analyzer

Best Practices

Troubleshooting

Variables Not Substituting

CLI Override Not Working

Conflicts with Claude Code Flags

Next Steps