Spryfile
A Markdown file that Spry treats as executable
A Spryfile is a Markdown file that Spry treats as executable.
Definition
A Spryfile is any Markdown file (.md) that contains:
Fenced code blocks with executable languages
Optional YAML frontmatter for configuration
Narrative prose explaining the workflow
Key Insight
A Spryfile is still valid Markdown. It renders normally in GitHub, VS Code, or any Markdown viewer. But when processed by Spry, the code blocks become runnable tasks.
Anatomy of a Spryfile
---
# Document Frontmatter (Optional)
project: My Workflow
version: 1.0
---
# Document Title
Introductory prose explaining what this workflow does.
## Section Heading
More explanatory text about this section.
```bash task-name --descr "What this task does"
# This is an executable code cell
echo "Hello, Spry!"
```
More narrative text...
## Another Section
```bash another-task --dep task-name
echo "This runs after task-name"
```Components
1. Frontmatter
YAML block at the top, delimited by ---:
---
project: Database Migration
version: 2.1.0
environment: ${env.DEPLOY_ENV}
database_url: ${env.DATABASE_URL}
---Frontmatter can:
- Define document metadata
- Configure execution behavior
- Include environment variable interpolation
- Classify sections semantically
2. Headings and Structure
Standard Markdown headings organize your workflow:
# Project Title (H1)
## Phase 1: Setup (H2)
### Subtask: Install Dependencies (H3)Spry understands this hierarchy and can use it for:
- Grouping related tasks
- Creating navigation
- Generating reports
3. Narrative Prose
Regular Markdown text explains your workflow:
## Database Migration
Before running the migration, ensure you have:
- Backed up the production database
- Notified the operations team
- Verified the staging migration succeeded
The following steps will apply changes to the production schema.This prose is preserved in the output and serves as documentation.
4. Code Cells
Fenced code blocks with special syntax:
```language identity --flags { attributes }
code content here
```See Code Cells for detailed syntax.
File Naming Conventions
Common patterns for Spryfile names:
| Pattern | Use Case |
|---|---|
Spryfile.md | Primary project workflow |
runbook.md | DevOps runbook |
playbook.md | SQLPage playbook |
deploy.md | Deployment workflow |
setup.md | Setup/initialization |
*.spry.md | Explicit Spryfile marker |
Spryfile vs Regular Markdown
| Feature | Regular Markdown | Spryfile |
|---|---|---|
| Code blocks | Display only | Executable |
| Frontmatter | Metadata only | Configuration |
| Dependencies | None | Supported |
| Output capture | None | Supported |
| Task ordering | None | DAG-based |
Multiple Spryfiles
You can organize complex projects across multiple files:
project/
├── setup.md # Environment setup
├── build.md # Build process
├── test.md # Test execution
├── deploy.md # Deployment
└── Spryfile.md # Main orchestrationEach file is independent but can share patterns and be run in sequence.
Validation
Spry validates Spryfiles for:
Syntax
Valid Markdown structure
Dependencies
No circular dependencies
Identities
Unique task names
Languages
Recognized executable languages
Run validation:
spry axiom ls myfile.mdBest Practices
Start with narrative - Explain what the workflow does
Group by phase - Use headings to organize related tasks
Document prerequisites - Note what's needed before running
Use meaningful names - deploy-production not step3
Add descriptions - --descr "Deploy to production server"
Be consistent - Follow your team's naming conventions
Include examples - Show expected output or usage
Explain dependencies - Why tasks depend on each other
Add context - Help future maintainers understand the workflow
Quick Summary
A Spryfile is Markdown that executes. It combines documentation with automation, making your workflows both readable and runnable.
How is this guide?
Last updated on