struckdown

QuickStart Guide

Get started with Struckdown in minutes.

Installation

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install struckdown
uv tool install git+https://github.com/benwhalley/struckdown

Configuration

Set your LLM credentials:

export LLM_API_KEY="sk-..."  # Your API key
export LLM_API_BASE="https://api.openai.com/v1"
export DEFAULT_LLM="gpt-4o-mini"

Your First Prompt

Test the CLI:

sd chat "Tell me a joke: [[joke]]"

This simple prompt asks the LLM to tell a joke and stores it in a variable called joke.

Basic Syntax

Completions (Slots)

Struckdown uses [[slot]] syntax to tell the LLM where to generate responses:

sd chat "Explain quantum physics: [[explanation]]"

The final slot can be omitted in simple prompts:

sd chat "Tell me a joke"  # Automatically becomes [[response]]

Typed Completions

Specify the type of response you want:

# Boolean (true/false)
sd chat "Is the sky blue? [[bool:answer]]"

# Pick from options
sd chat "Choose a color [[pick:color|red,green,blue]]"

# Number extraction
sd chat "Price: $19.99 [[number:price]]"

# Integer
sd chat "Count the words: 'hello world' [[int:count]]"

Template Variables

Use `` to reference previous results:

sd chat "Name a fruit: [[fruit]]

<checkpoint>

Tell me a joke about : [[joke]]"

Batch Processing

Process multiple files at once:

# Process text files
sd batch *.txt "Summarize in 5 words: [[summary]]" -o results.json

# Extract structured data
sd batch reviews/*.txt "Sentiment [[pick:sentiment|positive,negative,neutral]]" -o sentiment.csv

# Chain multiple operations
sd batch *.txt "Extract name: [[name]]" | \
  sd batch "Generate email for : [[email]]" -k

Memory Management with Checkpoints

Use <checkpoint> to create memory boundaries and save tokens:

sd chat "Long context...

Generate summary: [[summary]]

<checkpoint>

Translate  to Spanish: [[translation]]"

Everything before <checkpoint> is forgotten – only the extracted variables (``) are available in the next section.

Next Steps

• Tutorial – Learn Struckdown step-by-step
• Reference – Complete syntax documentation
• Custom Actions – Extend Struckdown with plugins
• Examples – Real-world examples
• CLI Usage – Complete CLI reference

Common Patterns

Extract structured data from files

sd batch documents/*.txt "
Name: [[name]]
Email: [[email]]
Phone: [[number:phone]]
" -o contacts.csv

Multi-step analysis

sd chat "Analyze this code:

\`\`\`python
def hello(): print('hi')
\`\`\`

Issues: [[issues]]

<checkpoint>

Issues found: 

Suggested fixes: [[fixes]]"

Classification pipeline

sd batch emails/*.txt "
Sentiment: [[pick:sentiment|positive,negative,neutral]]
Urgent: [[bool:urgent]]
Category: [[pick:category|sales,support,billing,other]]
" -o classified.json