From 16ea3697278bfaf322946d1ae2df369f709deb9d Mon Sep 17 00:00:00 2001
From: casey <casey@sarcio.org>
Date: Sat, 13 Jun 2026 11:04:12 +1000
Subject: [PATCH] added readme

---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0b26587
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# Alteryx Runner
+
+A Python-native runner for Alteryx `.yxmd` workflow files — no Alteryx installation required.
+
+## Prerequisites
+
+- **Python 3.11+**
+- **[uv](https://docs.astral.sh/uv/)** — fast Python package manager
+
+## Setup
+
+```bash
+# Install all dependencies
+uv sync
+```
+
+## Running a Workflow
+
+```bash
+uv run python -m alteryx_runner run <path/to/workflow.yxmd> [options]
+```
+
+### Example
+
+```bash
+uv run python -m alteryx_runner run ./Alteryx_TestWorkflows/Unique\&Sample/Unique\&Sample.yxmd --verbose
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--verbose` | Print Browse results and detailed execution log |
+| `--dry-run` | Parse and validate only — do not execute |
+| `--output-dir PATH` | Write output files to a specific directory |
+| `--param KEY=VALUE` | Set a workflow constant (repeatable) |
+| `--format [csv\|json\|parquet]` | Default output format for Browse nodes (default: `csv`) |
+
+### Dry-Run (Validate Only)
+
+Check that a workflow parses correctly without executing it:
+
+```bash
+uv run python -m alteryx_runner run ./Alteryx_TestWorkflows/JoinTesting/JoinTesting.yxmd --dry-run
+```
+
+### Custom Output Directory & Format
+
+```bash
+uv run python -m alteryx_runner run ./workflow.yxmd --output-dir ./results --format parquet
+```
+
+### Workflow Parameters
+
+Pass runtime constants with `--param`:
+
+```bash
+uv run python -m alteryx_runner run ./workflow.yxmd --param "StartDate=2024-01-01" --param "Region=West"
+```
+
+## Listing Supported Tools
+
+See all registered Alteryx tool plugins:
+
+```bash
+uv run python -m alteryx_runner list-tools
+```
+
+## Supported Tool Categories
+
+| Category | Tools |
+|---|---|
+| **In/Out** | Input Data, Output Data, Browse, Text Input |
+| **Preparation** | Filter, Formula, Multi-Field Formula, Multi-Row Formula, Select, Sort, Sample, Unique, Record ID, Auto Field, Generate Rows |
+| **Join** | Join, Join Multiple, Union, Append Fields, Find Replace |
+| **Parse** | DateTime, RegEx, Text To Columns |
+| **Transform** | Summarize, Cross Tab, Transpose |
+
+## Project Structure
+
+```
+alteryx_runner/
+├── cli.py              # CLI entry point
+├── engine/
+│   ├── parser.py       # .yxmd XML → workflow graph
+│   ├── executor.py     # Topological execution engine
+│   ├── graph.py        # DAG data structures
+│   └── context.py      # Runtime context & config
+├── expression/         # Alteryx expression parser
+└── tools/              # Tool implementations
+    ├── inout/          # Input Data, Output Data, Browse, Text Input
+    ├── join/           # Join, Union, Append Fields, Find Replace
+    ├── parse/          # DateTime, RegEx, Text To Columns
+    ├── preparation/    # Filter, Formula, Sort, Sample, Unique, …
+    └── transform/      # Summarize, Cross Tab, Transpose
+```