Axiom Text-UI

Spry Axiom Explorer — Text-UI CLI Overview

The Spry Axiom Explorer CLI is a lightweight, terminal-based interface built on top of the Spry framework to help developers and users interact with markdown docs, ontology graphs, and structured content directly from the command line. The CLI aims to streamline every-day workflows — browsing documentation, inspecting content structure, projecting subsets, or converting markdown into executable scripts — so you can work without leaving your terminal.

Spry is a lightweight TypeScript library that treats Markdown as a programmable medium, where every fence, section, and directive in your .md file can express behavior, not just formatting. The Runbook CLI (accessible via spry.ts or runbook.ts) is a Spry operator that allows you to execute code cells from markdown documents as tasks in a dependency graph (DAG).

spry.ts or runbook.ts :

import { CLI } from "../../../lib/axiom/text-ui/runbook.ts";

new CLI().run();

What Spry Does: It executes embedded code blocks, captures their outputs, composes multiple source types (SQL, HTML, JSON, shell, etc.) as executable “cells”, and treats sections as first-class programmable units with attributes, metadata, and dependency graphs.

Installation and Initialization

Install Deno 2.5 or higher and bootstrap your project:

cd <your-project>
deno run --node-modules-dir=auto -A https://raw.githubusercontent.com/programmablemd/spry/main/lib/sqlpage/cli.ts init
./spry.ts help

This creates:

• spry.ts - Executable wrapper to run Spry commands locally
• Spryfile.md - Executable Markdown defining tasks, SQL, and routes

---

Runbook

Axiom Runbook Quick Reference

Use Runbook CLI

After the Installation and Initialization To use the runbook cli, spry.ts content should be changed like:

#!/usr/bin/env -S deno run -A --node-modules-dir=auto
// Use `deno run -A --watch` in the shebang if you're contributing / developing Spry itself.

import { CLI } from "../../../lib/axiom/text-ui/runbook.ts";

new CLI().run();

---

Root Command

./spry.ts [command] [options]
# or
./runbook.ts [command] [options]

spry.ts or runbook.ts is simply the main entry point executable TypeScript file that provides the CLI interface. It is the file that contains the CLI definition. It provides access to several subcommands for managing and executing runbook tasks.

Commands

1. help

Display help information about available commands.

./spry.ts help

Purpose: Shows usage information and available commands.

---

2. completions - Generate Shell Completions

Generate shell completions for bash, fish, or zsh.

./spry.ts completions [shell]

Purpose: Generates auto-completion scripts for your shell environment to enable tab completion for Spry commands.

Supported Shells:

• bash - Generate completions for Bash
• fish - Generate completions for Fish
• zsh - Generate completions for Zsh

Options:

• -h, --help: Show help information
• -n, --name <command-name>: The name of the main command

---

2.1. completions bash

Generate shell completions for bash.

./spry.ts completions bash [options]

Setup:

Add the following line to your ~/.bashrc:

source <(./spry.ts completions bash)

Options:

• -n, --name <command-name>: The name of the main command

Example:

# Generate bash completions
./spry.ts completions bash

# Generate with custom command name
./spry.ts completions bash --name myspry

---

2.2. completions fish

Generate shell completions for fish.

./spry.ts completions fish [options]

Options:

• -n, --name <command-name>: The name of the main command

Example:

# Generate fish completions
./spry.ts completions fish

---

2.3. completions zsh

Generate shell completions for zsh.

./spry.ts completions zsh [options]

Options:

• -n, --name <command-name>: The name of the main command (Default: “spry.ts”)

Example:

# Generate zsh completions
./spry.ts completions zsh

# Generate with custom command name
./spry.ts completions zsh --name myspry

---

3. axiom - Spry Graph Viewer CLI

An internal module designed to support a text-UI (command-line or simplified UI) for certain operational tasks, documentation or workflows

3.1 help [command] - Show this help or the help of a sub-command

Displays detailed documentation and usage instructions for the selected command.

Usage:

./spry.ts axiom --help

Example:

./spry.ts axiom completions --help

3.2 completions - Generate shell completions

Enables shell auto-completion so when you type a command and press TAB, suggestions appear automatically. Supported shells: bash, fish, zsh.

Usage:

# Generate bash completions
./spry.ts axiom completions bash
# Generate fish completions
./spry.ts axiom completions fish
# Generate zsh completions
./spry.ts axiom completions zsh

3.3 web-ui [paths…] - Serve the markdown mdasts and Spry Ontology Graphs (SOGs)

Starts a local web server that displays:

• Graph representation of MD relationships
• Visual navigation of documents & sections
• Spry Ontology Graphs (SOG UI)

This makes it easy to understand document topology and structure visually instead of reading raw Markdown.

Usage:

./spry.ts axiom web-ui

With specific file:

./spry.ts axiom web-ui < path to md file >

3.4 ls [paths…] - browse containedInSection hierarchy as a tree

Lists document nodes in a tree view, based on containedInSection hierarchy. Helps explore structure depth, table of contents, and nested headers.

Usage:

./spry.ts axiom ls

With specific file:

./spry.ts axiom ls < path to md file >

Example:

./spry.ts axiom ls ./runbook.md

3.5 inspect [paths…] - inspect mdast nodes as a hierarchy

Usage:

./spry.ts axiom inspect

./spry.ts axiom inspect < path to md file >

3.6 projection [paths…] - compute a projection and emit as JSON (defaults to flexible)

Usage:

./spry.ts axiom projection

./spry.ts axiom projection < path to md file >

3.7 shebang [paths…] - convert markdown files into executables with shebang (#!) helpers

Usage:

./spry.ts axiom shebang

./spry.ts axiom shebang < path to md file >

4. ls - List Tasks

List all code cells (tasks) found in markdown documents in a tabular format.

./spry.ts ls [paths...] [options]

Purpose: List code cells (tasks) in markdown documents.

Arguments:

• [paths...]: Optional paths to markdown files or URLs. If not provided, uses default files from configuration (typically Spryfile.md).

Options:

• -h, --help: Show help information
• --no-color: Display output without ANSI colors

Examples:

# List tasks from default files (Spryfile.md)
./spry.ts ls

# List tasks from local file
./spry.ts ls ./Spryfile.md

# List tasks from remote URL
./spry.ts ls https://raw.githubusercontent.com/programmablemd/spry/main/support/assurance/scf/Spryfile.md

# List tasks from multiple sources
./spry.ts ls ./Spryfile.md ./tasks.md

# List without colors
./spry.ts ls ./Spryfile.md --no-color

Output Columns:

• NAME: Task identifier

• ENGINE: Execution engine (shebang or deno-task)

• DEPS: Task dependencies (comma-separated)

• FLAGS: Task flags indicating:

• E: Has errors/issues (red)

• I: Is interpolated (yellow)

• CF/CM: Capture mode (File or Memory, blue)

• G: Git ignored

• S: Silent execution

• DESCR: Task description

• ORIGIN: Source file path

• GRAPH: Graph membership (comma-separated)

---

5. task - Execute Specific Task

Execute a single task and its dependencies.

./spry.ts task <taskId> [paths...] [options]

Purpose: Execute a specific cell and dependencies.

Arguments:

• <taskId>: (Required) The identifier of the task to execute
• [paths...]: Optional paths to markdown files or URLs

Options:

• -h, --help: Show help information
• --verbose <style>: Emit verbose information messages
• Values: plain, rich, markdown
• --summarize: Emit execution summary in JSON format after completion

Examples:

# Execute specific task from default files
./spry.ts task setup-database

# Execute task from specific file
./spry.ts task setup-database ./Spryfile.md

# Execute task with verbose output (plain text)
./spry.ts task deploy-app --verbose plain

# Execute task with rich formatting
./spry.ts task deploy-app --verbose rich

# Execute task with markdown output
./spry.ts task deploy-app --verbose markdown

# Execute task and show JSON summary
./spry.ts task deploy-app ./Spryfile.md --summarize

# Execute task with verbose and summarize
./spry.ts task deploy-app --verbose rich --summarize

Behavior:

• Executes the specified task and all its dependencies
• Tasks are executed in dependency order
• Shows error if task is not found
• With --verbose, displays detailed execution information
• With --summarize, outputs JSON summary of execution results

---

6. run - Execute All Tasks

Execute all code cells in markdown documents as a directed acyclic graph (DAG).

./spry.ts run [paths...] [options]

Purpose: Execute all code cells in markdown documents as a DAG.

Arguments:

• [paths...]: Optional paths to markdown files or URLs

Options:

• -h, --help: Show help information
• --verbose <style>: Emit verbose information messages
• Values: plain, rich, markdown
• --graph <name>: Run only tasks in specified graph(s). Can be used multiple times to include multiple graphs
• --summarize: Emit execution summary in JSON format after completion
• --visualize <style>: Visualize the execution DAG instead of running it
• Values: ascii-tree, ascii-workflow, ascii-flowchart, mermaid-js

Examples:

# Run all tasks from default files (Spryfile.md)
./spry.ts run

# Run tasks from specific file
./spry.ts run ./Spryfile.md

# Run tasks with plain verbose output
./spry.ts run ./Spryfile.md --verbose plain

# Run tasks with rich verbose output
./spry.ts run ./Spryfile.md --verbose rich

# Run tasks with markdown output
./spry.ts run --verbose markdown

# Run only tasks in specific graph
./spry.ts run --graph deployment

# Run tasks from multiple graphs
./spry.ts run --graph setup --graph deployment

# Run with multiple files and graph filter
./spry.ts run ./Spryfile.md ./tasks.md --graph production

# Visualize the DAG as ASCII tree (without executing)
./spry.ts run --visualize ascii-tree

# Visualize as ASCII workflow diagram
./spry.ts run --visualize ascii-workflow

# Visualize as ASCII flowchart
./spry.ts run --visualize ascii-flowchart

# Visualize as Mermaid.js diagram
./spry.ts run --visualize mermaid-js

# Run with summary output
./spry.ts run ./Spryfile.md --summarize

# Run with verbose and summarize
./spry.ts run --verbose rich --summarize

# Run specific graph with visualization first
./spry.ts run --graph deployment --visualize ascii-tree
# Then execute
./spry.ts run --graph deployment

Behavior:

• Parses all markdown files and extracts code cells as tasks
• Builds a dependency graph from task relationships
• Executes tasks in topological order respecting dependencies
• Can filter tasks by graph membership using --graph
• Supports visualization mode to inspect the execution plan without running
• With --summarize, outputs JSON summary of execution results

Visualization Styles:

1. ascii-tree: Simple tree representation of task dependencies
2. ascii-workflow: Workflow-style diagram showing task flow
3. ascii-flowchart: Flowchart representation of the DAG
4. mermaid-js: Generates Mermaid.js diagram code for the DAG

---

Verbose Styles

The --verbose option accepts three styles:

1. plain: Simple text output without formatting
2. rich: Colored and formatted output with visual enhancements (default for most use cases)
3. markdown: Output formatted as markdown document

---

Task Flags Explanation

When using the ls command, tasks display flags indicating their properties:

• E (Error): Task has validation issues or errors (displayed in bright red)
• I (Interpolated): Task content includes variable interpolation (displayed in bright yellow)
• CF (Capture File): Task captures output to a relative file path (displayed in blue)
• CM (Capture Memory): Task captures output to memory (displayed in blue)
• G (Git Ignored): Task output is configured to be git-ignored
• S (Silent): Task runs silently without standard output

---

Supported Code Languages

The CLI recognizes code blocks with the following language identifiers as spawnable tasks:

• shell / bash: Shell scripts (primary spawnable language)
• sql: SQL queries and migrations
• python: Python scripts
• typescript / javascript: TypeScript/JavaScript code
• Custom languages can be extended through the language registry

---

Task Execution Engines

Tasks can be executed using different engines:

1. shebang: Uses the shebang line (#!/bin/...) to determine interpreter (displayed in green)
2. deno-task: Executes as a Deno task (displayed in cyan)

The engine is automatically detected based on the code content.

---

File Sources

All commands that accept file paths support:

1. Local file system paths: ./Spryfile.md, /path/to/file.md
2. Remote URLs: https://raw.githubusercontent.com/programmablemd/spry/main/Spryfile.md
3. Multiple sources: Mix of local and remote files
4. Directories: Can specify directories containing markdown files

---

Configuration

The CLI can be configured with:

• defaultFiles: Array of files to load when no paths are provided (e.g., Spryfile.md)
• isSpawnable: Custom function to determine if a code block is spawnable
• mdastCLI: Custom mdast CLI configuration

---

Common Patterns

Extract and Execute Pattern

# First, visualize what will run
./spry.ts run --visualize ascii-tree

# Then execute
./spry.ts run --verbose rich

# Or for specific graph
./spry.ts run --graph production --visualize ascii-tree
./spry.ts run --graph production --verbose rich

Development Pattern

# List tasks to find task IDs
./spry.ts ls ./Spryfile.md

# Execute specific task during development
./spry.ts task setup-database ./Spryfile.md --verbose rich

# Run full workflow when ready
./spry.ts run ./Spryfile.md --graph development

CLI

Axiom CLI Quick Reference

Use CLI

After the Installation and Initialization To use the text-ui cli, spry.ts content should be changed like:

#!/usr/bin/env -S deno run -A --node-modules-dir=auto
// Use `deno run -A --watch` in the shebang if you're contributing / developing Spry itself.

import { CLI } from "../../../lib/axiom/text-ui/cli.ts";

new CLI().run();

---

Root Command

./spry.ts [command] [options]
# or
./cli.ts [command] [options]

spry.ts or cli.ts is simply the main entry point executable TypeScript file that provides the CLI interface. It is the file that contains the CLI definition. It provides access to several subcommands for managing and executing runbook tasks.

Commands

1. help

Display help information about available commands.

./spry.ts help

Purpose: Shows usage information and available commands.

---

2. completions - Generate Shell Completions

Generate shell completions for bash, fish, or zsh.

./spry.ts completions [shell]

Purpose: Generates auto-completion scripts for your shell environment to enable tab completion for Spry commands.

Supported Shells:

• bash - Generate completions for Bash
• fish - Generate completions for Fish
• zsh - Generate completions for Zsh

Options:

• -h, --help: Show help information
• -n, --name <command-name>: The name of the main command

---

2.1. completions bash

Generate shell completions for bash.

./spry.ts completions bash [options]

Options:

• -n, --name <command-name>: The name of the main command

Example:

# Generate bash completions
./spry.ts completions bash

# Generate with custom command name
./spry.ts completions bash --name myspry

---

2.2. completions fish

Generate shell completions for fish.

./spry.ts completions fish [options]

Options:

• -n, --name <command-name>: The name of the main command

Example:

# Generate fish completions
./spry.ts completions fish

---

2.3. completions zsh

Generate shell completions for zsh.

./spry.ts completions zsh [options]

Options:

• -n, --name <command-name>: The name of the main command (Default: “spry.ts”)

Example:

# Generate zsh completions
./spry.ts completions zsh

# Generate with custom command name
./spry.ts completions zsh --name myspry

---

3 web-ui [paths…] - Serve the markdown mdasts and Spry Ontology Graphs (SOGs)

Starts a local web server that displays:

• Graph representation of MD relationships
• Visual navigation of documents & sections
• Spry Ontology Graphs (SOG UI)

This makes it easy to understand document topology and structure visually instead of reading raw Markdown.

Usage:

./spry.ts web-ui

With specific file:

./spry.ts web-ui < path to md file >

4 ls [paths…] - browse containedInSection hierarchy as a tree

Lists document nodes in a tree view, based on containedInSection hierarchy. Helps explore structure depth, table of contents, and nested headers.

Usage:

./spry.ts ls

With specific file:

./spry.ts  ls < path to md file >

Example:

./spry.ts ls ./runbook.md

5 inspect [paths…] - inspect mdast nodes as a hierarchy

Usage:

./spry.ts inspect

./spry.ts inspect < path to md file >

6 projection [paths…] - compute a projection and emit as JSON (defaults to flexible)

Usage:

./spry.ts projection

./spry.ts projection < path to md file >

7 shebang [paths…] - convert markdown files into executables with shebang (#!) helpers

Usage:

./spry.ts shebang

./spry.ts shebang < path to md file >

---