Quick Start

Let's create and execute your first executable Markdown file in under 5 minutes. By the end of this guide, you'll have a working Spry project with a simple task that you can execute.

Initialize a Project

Create a new directory and initialize a Spry project:

# Create project directory
mkdir my-spry-project && cd my-spry-project

# Initialize with SQLPage template
spry sp init

This creates three important files:

File	Purpose
`Spryfile.md`	Your executable Markdown document

Examine the Generated Spryfile

Open Spryfile.md to see the structure. It contains:

YAML Frontmatter - Configuration settings:

---
sqlpage-conf:
  allow_exec: true
  port: ${env.PORT}
  database_url: ${env.SPRY_DB}
  web_root: ./dev-src.auto
---

Environment Setup - Environment variables in an executable code block:

```envrc prepare-env -C ./.envrc --gitignore --descr "Generate .envrc file and add it to local .gitignore if it's not already there"
export SPRY_DB="sqlite://sqlpage.db?mode=rwc"
export PORT=9227
```

Click here to see more about environment setup.

Development Task - A task to start the development server:

```bash prepare-sqlpage-dev
spry sp spc --fs dev-src.auto --destroy-first --conf sqlpage/sqlpage.json
```

Notice how each code block has a task ID (like prepare-env) after the language name. This makes the block executable.

List Available Tasks

See all executable tasks in your Spryfile:

spry rb ls

Output:

Tasks in Spryfile.md:
  - prepare-env (envrc)
  - prepare-sqlpage-dev (bash)

The rb ls command shows you every executable code block with its task ID and language.

Execute a Specific Task

Run the environment setup task:

spry rb task prepare-env

This creates a .envrc file with your environment variables and automatically adds it to .gitignore.

Task Executed Successfully!

Check your directory - you should now see a .envrc file with your environment variables.

Execute All Tasks

Run all tasks in dependency order:

spry rb run

Spry automatically determines the correct execution order based on dependencies between tasks.

Create a Simple Task

Let's add a custom task to the Spryfile to understand the structure better.

Add a New Task

Open Spryfile.md and add this section:

## Hello World Task

This task demonstrates basic Spry execution.

```bash hello-world --descr "Print a greeting message"
#!/usr/bin/env -S bash
echo "Hello from Spry!"
echo "Current directory: $(pwd)"
echo "Task executed at: $(date)"
```

The task structure is:

Language: bash
Task ID: hello-world
Description: --descr "Print a greeting message"
Content: The actual shell script

Execute Your New Task

Run the task you just created:

spry rb task hello-world

You should see:

Hello from Spry!
Current directory: /path/to/my-spry-project
Task executed at: Thu Dec 11 10:30:00 UTC 2025

View Execution Details

Get detailed output with the verbose flag:

spry rb task hello-world --verbose rich

This shows additional information about the task execution, including timing and status.

Add Task Dependencies

Let's create tasks that depend on each other to see how Spry orchestrates execution.

## Multi-Step Workflow

### Step 1: Clean

```bash clean --descr "Remove old files"
echo "Cleaning up..."
rm -rf output/
mkdir -p output/
echo "Clean complete!"
```

### Step 2: Build

```bash build --dep clean --descr "Build the project"
echo "Building..."
echo "Build artifact" > output/app.txt
echo "Build complete!"
```

### Step 3: Deploy

```bash deploy --dep build --descr "Deploy the application"
echo "Deploying..."
cat output/app.txt
echo "Deploy complete!"
```

Now execute the deployment task:

spry rb task deploy

Automatic Dependency Resolution

When you run deploy, Spry automatically executes clean first, then build, and finally deploy - all in the correct order!

Visualize Your Workflow

See the task execution flow visually:

spry rb run --visualize ascii-tree

This shows a directed acyclic graph (DAG) of your tasks:

clean
  └─→ build
       └─→ deploy

Development with Live Reload

For SQLPage applications, you can enable watch mode for automatic rebuilding:

spry sp spc --fs dev-src.auto --destroy-first \
  --conf sqlpage/sqlpage.json --watch --with-sqlpage

This:

Watches Spryfile.md for changes
Automatically rebuilds when you save
Restarts the SQLPage server
Opens your browser to http://localhost:9227

Development Mode Only

Watch mode is intended for development. For production, use --package to bundle your application into the database.

Common Task Options

Here are the most useful options for code blocks:

Option	Purpose	Example
`--descr "..."`	Human-readable description	`--descr "Build the app"`
`--dep task1,task2`	Task dependencies	`--dep clean,test`
`--silent`	Suppress output	`--silent`
`-C <path>`	Capture output to file	`-C ./results.json`
`--gitignore`	Add captured file to .gitignore	`--gitignore`

Example with multiple options:

```bash test --descr "Run test suite" --dep build --silent
npm test
```

# macOS
brew install direnv

# Ubuntu/Debian
sudo apt-get install direnv

Configure Your Shell

Add to your shell configuration:

# For bash (~/.bashrc)
eval "$(direnv hook bash)"

# For zsh (~/.zshrc)
eval "$(direnv hook zsh)"

Create .envrc File

Spry can generate .envrc files automatically:

```envrc prepare-env -C ./.envrc --gitignore --descr "Generate .envrc file and add it to local .gitignore if it's not already there"
export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227


Then allow direnv to load it:
```bash
direnv allow

Manual Environment Setup

If you prefer not to use direnv, you can source environment files manually:

# Create environment file
cat > .envrc << 'EOF'
export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227
EOF

# Load environment
source .envrc

How is this guide?

Quick Start

Quick Start

Initialize a Project

Examine the Generated Spryfile

List Available Tasks

Execute a Specific Task

Execute All Tasks

Create a Simple Task

Add a New Task

Execute Your New Task

View Execution Details

Add Task Dependencies

Visualize Your Workflow

Development with Live Reload

Common Task Options

Environment Setup

Using direnv (Recommended)

Install direnv

Configure Your Shell

Create .envrc File

Manual Environment Setup

On this page