Structured results
Jobs publish a predictable snapshot with service identity, status, timing, summary data, and artifacts. Instead of treating every script as a special case, the runner gives every job the same reporting language.
PageDragon tooling
PD Runner
PD Runner turns repeatable operations work into reliable, dashboard-ready reporting. It runs service jobs, captures their results, and packages the outcome so teams can see what happened without digging through logs or private systems.
What it does
PD Runner solves a common operations problem: important checks and data pulls happen repeatedly, but their results often end up scattered across shell output, logs, one-off files, and vendor portals. PD Runner gives those jobs a consistent lifecycle and a consistent result shape.
Each configured service can run on demand or on a schedule. The service returns a normalized status, summary, data payload, and optional artifacts. That makes the output usable by humans, dashboards, automations, and audit workflows.
PD Runner is intentionally not a web server, auth system, or database. It is the operational layer that runs the work and prepares structured results for a separate presentation layer.
Output contract
data/services/<service_id>/latest.json data/artifacts/<service_id>/<run_id>/... static/data/manifest.json static/data/<service_id>/latest.json
Where PD Runner differs
Dashboard handoff
Runner state can be exported directly into a static dashboard. The dashboard stays fast and simple because it reads prepared JSON instead of calling private services at runtime.
Protected secrets
Secrets are treated as runtime-only configuration. They are not baked into the public dashboard output, and sensitive artifacts are excluded unless a private deployment explicitly opts in.
Plugin system
A PD Runner plugin is a service worker. The runner loads service configuration, finds the matching worker, gives it a run context, and lets the worker return normalized data.
Plugins can be scheduled as top-level services, kept manual-only, or used as chained services that run when another worker calls them. That makes it possible to split a larger workflow into small, named jobs without turning the runner into a heavy orchestration platform.
The plugin boundary keeps the runner generic. The runner owns scheduling, execution, storage, and dashboard export; each plugin owns the domain-specific work for one service.
Quick start
cd <pd-runner-repo> pip install -e . pd init pd validate pd list-services pd run-service usgs_earthquake pd run-services
Command reference
pd [--config <dir>] [--verbose] <command>
Runs PD Runner with an optional config directory and verbose logging.
| Argument | Description |
|---|---|
| --config, -c <dir> | Configuration directory. Defaults to config. |
| --verbose, -v | Enable verbose logging. |
pd init
Initializes a headless PD Runner workspace with config, plugin, and data directories.
pd validate
Validates YAML configuration and reports loaded services and views.
pd list-services
Lists configured services, enabled state, schedule type, and worker module.
pd init-env [--force] [--split]
Writes example environment variable files for bundled plugins.
| Argument | Description |
|---|---|
| --force | Overwrite existing example files. |
| --split | Write per-service example files instead of one combined example. |
pd run-service <service_id> [--data-dir <dir>]
Runs one service by id and persists its latest snapshot and artifacts.
| Argument | Description |
|---|---|
| <service_id> | Configured service id to execute. |
| --data-dir <dir> | Runner data directory. Defaults to the workspace data directory. |
pd run-services [--data-dir <dir>] [--services <ids>] [--all-services]
Runs enabled scheduled services by default, then persists latest snapshots and artifacts.
| Argument | Description |
|---|---|
| --data-dir <dir> | Runner data directory. Defaults to the workspace data directory. |
| --services <ids> | Comma-separated service ids to run. |
| --all-services | Include unscheduled manual or chained services in the top-level run set. |
pd init-dashboard --target <dir> [--with-netlify-identity|--no-netlify-identity]
Initializes a managed dashboard website target.
| Argument | Description |
|---|---|
| --target <dir> | Website output directory to manage. Required. |
| --with-netlify-identity | Include Netlify Identity wiring. |
| --no-netlify-identity | Generate without Netlify Identity wiring. |
pd generate-dashboard --target <dir> [options]
Generates dashboard files from existing latest snapshots.
| Argument | Description |
|---|---|
| --target <dir> | Website output directory. Required. It may be a deployable static site folder or another managed target folder. |
| --wipe | Wipe generated content while preserving git metadata, dependencies, and local framework cache. |
| --wipe-all | Wipe more aggressively, preserving only git metadata and the dashboard sentinel. |
| --data-dir <dir> | Runner data directory. |
| --services <ids> | Comma-separated service ids to include. |
| --copy-artifacts | Copy service artifacts into static dashboard output. |
| --include-sensitive | Include artifacts marked sensitive. Use only for private dashboards. |
| --git-commit | Commit generated changes when the website directory is version controlled. |
| --git-push | Push committed dashboard changes. |
| --branch <name> | Branch to push. Defaults to main. |
| --message <text> | Commit message. Defaults to Update dashboard. |
| --with-netlify-identity / --no-netlify-identity | Override the dashboard identity setting. |
pd update-dashboard --target <dir> [--run-services|--from-latest] [options]
Updates a dashboard, optionally running services first.
| Argument | Description |
|---|---|
| --run-services | Run services before generating the dashboard. |
| --from-latest | Generate from existing latest snapshots. This is the default. |
| --all-services | When running services, include unscheduled manual or chained services. |
| All generate-dashboard options | Accepts the same target, wipe, service, artifact, git, identity, and message options. |