rundot 0.6.0__tar.gz

rundot-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI - Lint and Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14", "3.15-dev"]
+    steps:
+      #----------------------------------------------
+      #       check-out repo and set-up python
+      #----------------------------------------------
+      - name: Check out repository
+        uses: actions/checkout@v7
+      - name: Set up python
+        id: setup-python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{matrix.python-version}}
+      #----------------------------------------------
+      #  -----  install & configure uv  -----
+      #----------------------------------------------
+      # Pointing uv at the interpreter setup-python installed overrides .python-version,
+      # which would otherwise make every matrix entry run on 3.14.
+      - name: Install UV
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ steps.setup-python.outputs.python-path }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      #----------------------------------------------
+      # install dependencies
+      #----------------------------------------------
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Show Python version
+        run: uv run python --version
+      #----------------------------------------------
+      # Run linting and tests
+      #----------------------------------------------
+      - name: Ruff format check
+        run: |
+          uv run ruff format --check .
+      - name: Ruff linting
+        run: |
+          uv run ruff check .
+      - name: Type check with ty
+        run: |
+          uv run ty check
+      - name: Check import contracts
+        run: |
+          make lint-imports
+      - name: Build docs
+        run: |
+          uv run zensical build --strict
+      - name: Test with pytest
+        run: |
+          uv run pytest -vv --cov=rundot --cov-branch --cov-report=term-missing --cov-config=pyproject.toml

rundot-0.6.0/.gitignore

@@ -0,0 +1,21 @@
+.venv/
+.ty_cache/
+.ruff_cache/
+.import_linter_cache/
+.pytest_cache/
+.idea/
+__pycache__
+.DS_Store
+dist/
+site/
+htmlcov/
+*.coverage*
+coverage.xml
+.cache/
+
+# Transcripts written by running the fixture runbooks by hand
+tests/runbooks/logs/
+
+# Transcripts written by releasing rundot with PUBLISHING.md, or running the examples by hand
+/logs/
+examples/logs/

rundot-0.6.0/.python-version

@@ -0,0 +1 @@
+3.14

rundot-0.6.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Change log
+
+## Unreleased
+
+- **Breaking:** paulrun is now called rundot. Install it as `rundot`, and run it as `rundot` instead of `paulrun`. Subcommands and flags are unchanged.
+    - The package is `rundot`, so imports are `from rundot.backends import ...`.
+    - Backends register in the `rundot.backends` entry point group, which was `paulrun.backends`.
+    - `PAULRUN_LIBRARY` is now `RUNDOT_LIBRARY`.
+    - `PAULRUN_RUNBOOK_DIR`, set for blocks, is now `RUNDOT_RUNBOOK_DIR`.
+    - The docs are at [docs.rundot.dev](https://docs.rundot.dev/) and the code at [github.com/phalt/rundot](https://github.com/phalt/rundot).
+
+## 0.6.0
+
+- `paulrun run`'s output is easier to scan:
+    - the overview and how the run finished are in boxes
+    - each step is a numbered blue rule, e.g. `1/3  Build`
+    - each block is a bracket: `┌` with its language and when it started (`HH:MM:SS.mmm`), each line it printed after `│`, then `└ ✓ exit 0 · 0.4s` or `└ ✗ exit 3 · 0.4s`
+    - docstrings are dim, and confirms are in a yellow box
+- A line a block writes to stderr has a red `│`.
+- Code is hidden unless you pass `--show-code`. `--dry` always shows it.
+- The transcript is unchanged.
+- Backends: `output` takes an optional `stderr=True` for a stderr line, and `stream()` passes it when `output` accepts it. A backend that calls `output(line)` still works.
+
+## 0.5.0
+
+- A block's output is fenced off between `=== LOG: <when it started> ===` and `========`, with the time to the microsecond and a blank line either side, so it can't be mistaken for the block's code or paulrun's own lines. A block that prints nothing gets no LOG section. Under `--step`, a blank line comes before and after `Run this block?` too. The transcript is unchanged.
+
+## 0.4.0
+
+- Add a cool logo to the cli output
+
+## 0.3.0
+
+- A runbook can set `step: true` in its frontmatter to always run as if `--step` was given, asking before each `run` block. `--no-step` runs it straight through. `check` reports a `step` that isn't `true` or `false`.
+- The book picker, `paulrun run` with no runbook, now takes `q` to quit, and says so: `Run which? (q to quit)`.
+- A block skipped under `--step` is now shown, and recorded in the transcript, as `skipped` rather than `skipped (--step)`, since `step: true` skips blocks too.
+
+## 0.2.0
+
+### A runbook library
+- keep runbooks you use across projects in `~/runbooks`, or wherever `PAULRUN_LIBRARY` says. Then run one by name from anywhere, e.g. `paulrun rebuild-frontend`. `run`, `check` and `inputs` all take a book's name as well as a path, and a file where you are is always used before a book with the same name. `paulrun library` lists the books in your library, with each one's title and description. `paulrun run`, with no runbook, lists them by number and runs the one you pick.
+- A new docs page, [Your runbook library](https://docs.rundot.dev/library/), with a worked example of a book that rebuilds a frontend under nvm.
+
+- **Breaking:** `paulrun go` is now `paulrun run`, and you don't need to type it: `paulrun RELEASING.md` runs `RELEASING.md`. Anything after `paulrun` that isn't a command is a runbook to run, so `paulrun go` is no longer a command. `paulrun` on its own still shows help.
+- **Breaking:** blocks now run in the folder you run paulrun from, not the folder the runbook is in. A relative `output_path` is now relative to that folder too. A runbook kept at the root of its project, run from there, works as before. One run as `paulrun path/to/RUNBOOK.md` from another folder now works on that other folder and writes its transcript there. This includes blocks run by external backends, whose `cwd` is now the folder paulrun was started from.
+- Blocks get `PAULRUN_RUNBOOK_DIR`, the folder the runbook is in, so a runbook can still use files kept next to it.
+- Running a runbook shows the folder blocks will run in, as `directory:` straight after the title, so you can check it before answering `Start?`. `--dry` shows it too.
+- `paulrun library`, the book picker and `paulrun inputs` are in colour in a terminal: names you type are bold cyan, details are dim, and secrets and problems stand out. Piped output has no colour, as before.
+- Inputs can have a `default`, shown at the prompt and used when you press enter. The environment still comes first. `check` reports a default that isn't text, doesn't match the input's `pattern`, or is on a secret.
+- Inputs can have `choices`: the only values accepted, listed at the prompt. You type the choice itself, and a value from the environment has to be one of them too. `check` reports choices that aren't a list of text, a choice the `pattern` refuses, a default that isn't a choice, and choices on a secret.
+
+## 0.1.0
+
+Initial release. paulrun runs hand-written markdown runbooks.
+
+- `paulrun go` runs a runbook's steps in order, streaming each block's output as it's printed and stopping at the first block that fails.
+- `run` blocks for shell (`sh`, `bash`, `shell`) and Python (`python`, `py`), with the `python` frontmatter key to choose the interpreter.
+- `docstring` blocks to show notes as the runbook runs, and `confirm` blocks to pause for steps done by hand.
+- `input` blocks to ask for a value part way through a run, once it exists: a pull request number from a step done by hand, or a one-time code that expires in seconds.
+- Inputs, collected from the environment or by asking, with an optional `pattern` to check them against. Plain inputs fill in `<NAME>` placeholders; secrets are hidden as you type them and replaced with `****` everywhere paulrun shows or records them.
+- `paulrun go --dry` to see every block with its inputs filled in, without running anything.
+- `paulrun go --step` to run, skip or quit at each block.
+- Transcripts: with `output_path` set, every run is added to a plain record of what ran, what it printed and how it finished.
+- Ctrl-C stops a run cleanly, letting a running block stop and recording how far the run got.
+- `paulrun check` to find problems before running anything: missing or malformed frontmatter, undeclared placeholders, secrets used as placeholders, blocks outside a step, and shell and Python syntax errors, with shellcheck warnings when it's installed.
+- `paulrun inputs` to list the inputs a runbook needs, and `paulrun backends` to list the languages paulrun can run.
+- Backends for other languages can be added by any package, through the `paulrun.backends` entry point group.

rundot-0.6.0/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+## Workflow
+
+### Workflow for planned tasks
+
+1. Read the plan, spec and todos, then present a short plan. STOP and wait for my approval.
+2. Implement test-first in red-green slices. Keep 100% line and branch coverage.
+3. Only tick checkboxes or approval boxes when I say so, or after CI is confirmed green.

rundot-0.6.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# rundot Code of Conduct
+
+Like the technical community as a whole, the rundot team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people.
+
+Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.
+
+This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
+
+This code of conduct applies to all spaces managed by the rundot project or Paul Hallett. This includes the issue tracker, pull requests, discussions, and any other forums created by the project team which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.
+
+If you believe someone is violating the code of conduct, we ask that you report it by emailing [paulandrewhallett@gmail.com](mailto:paulandrewhallett@gmail.com).
+
+- **Be friendly and patient.**
+- **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
+- **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
+- **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the rundot community should be respectful when dealing with other members as well as with people outside the rundot community.
+- **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
+  - Violent threats or language directed against another person.
+  - Discriminatory jokes and language.
+  - Posting sexually explicit or violent material.
+  - Posting (or threatening to post) other people's personally identifying information ("doxing").
+  - Personal insults, especially those using racist or sexist terms.
+  - Unwelcome sexual attention.
+  - Advocating for, or encouraging, any of the above behavior.
+  - Repeated harassment of others. In general, if someone asks you to stop, then stop.
+- **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and rundot is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of rundot comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
+
+Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html).
+
+## Questions?
+
+If you have questions, please see [CONTRIBUTING.md](CONTRIBUTING.md). If that doesn't answer your questions, feel free to [contact us](mailto:paulandrewhallett@gmail.com).

rundot-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,158 @@
+# Contributing
+
+First things first: thank you for contributing! This project will be successful thanks to everyone who contributes, and we're happy to have you.
+
+## AI disclosure
+
+Within rundot we use coding agents to prototype and build out ideas, and then take the idea to fruition using human reviewed and approved code.
+
+You, the human and the author of changes are responsible for the contributions, and if you cannot confidently explain or demonstrate understanding of the changes you are contributing, then they will not be accepted.
+
+## Bug or issue?
+
+To raise a bug or issue please use [our GitHub](https://github.com/phalt/rundot/issues).
+
+Please check the issue has not been raised before by using the search feature.
+
+When submitting an issue or bug, please make sure you provide thorough detail on:
+
+1. The version of rundot you are using (`rundot --version`)
+2. Your operating system and Python version
+3. Any errors or outputs you see in your terminal
+4. The smallest runbook that shows the problem (this is particularly important). Take out any secrets first!
+
+## Contribution
+
+If you want to directly contribute you can do so in two ways:
+
+1. Documentation
+2. Code
+
+### Documentation
+
+We use [Zensical](https://zensical.org/) and [GitHub pages](https://pages.github.com/) to deploy our docs.
+
+Fixing grammar, spelling mistakes, or expanding the documentation to cover features that are not yet documented, are all valuable contributions.
+
+Please see the **Set up** instructions below to run the docs locally on your computer, then:
+
+```sh
+make docs-serve
+```
+
+The examples in the docs and the README are tested, so if you change one, run `make test` too.
+
+### Code
+
+Contribution by writing code for new features, or fixing bugs, is a great way to contribute to the project.
+
+Please [open an issue](https://github.com/phalt/rundot/issues) to talk it through before changing the runbook format (frontmatter keys, what a fence does, placeholders or the transcript), adding a command or flag, or adding a dependency. These are hard to change once people's runbooks rely on them.
+
+#### Set up
+
+Clone the repo:
+
+```sh
+git clone git@github.com:phalt/rundot.git
+cd rundot
+```
+
+Move to a feature branch:
+
+```sh
+git switch -c my-branch-name
+```
+
+Install UV (if not already installed):
+
+```sh
+# On macOS and Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or using pip:
+pip install uv
+```
+
+Install all the dependencies:
+
+```sh
+make install
+```
+
+This will use UV to create a virtual environment and install all dependencies, including rundot itself, so its built-in backends are registered. UV handles the virtual environment automatically, so you don't need to manually activate it.
+
+To make sure you have things set up correctly, please run the tests:
+
+```sh
+make test
+```
+
+You can run your copy of rundot with `uv run rundot`, e.g. on one of the example runbooks in `tests/runbooks/`:
+
+```sh
+uv run rundot tests/runbooks/two_steps.md
+```
+
+Run `make help` to see every command.
+
+### Adding a backend
+
+rundot runs shell and Python blocks out of the box. To add another language to rundot itself:
+
+1. Write `rundot/backends/<name>.py`, implementing the backend protocol
+2. Add one entry point line for it in `pyproject.toml`, then run `make install`
+3. Write `tests/backends/test_<name>.py`, which really runs blocks (skipped if the language isn't installed)
+4. Add a section about it to `docs/backends.md`
+5. Add a CHANGELOG entry
+
+[docs/backends.md](https://docs.rundot.dev/backends/) explains each step, and how backends work.
+
+A backend doesn't have to be part of rundot: the same page shows how to ship one in your own package.
+
+### Preparing changes for review
+
+Once you've made changes, here's a good checklist to run through before publishing for review:
+
+Format and lint the code:
+
+```sh
+make format
+```
+
+Check the types:
+
+```sh
+make ty
+```
+
+Check the import contracts:
+
+```sh
+make lint-imports
+```
+
+[Import Linter](https://import-linter.readthedocs.io/) checks that modules only import in the directions we want: `rundot.cli` sits on top and wires everything together, the runner and validator never import the CLI or each other, backends are only loaded through their entry points, and only the CLI uses `click` and `rich`. The contracts, and the reasons for them, are under `[tool.importlinter]` in `pyproject.toml`. If one breaks, change the import rather than the contract.
+
+Run the tests:
+
+```sh
+make test
+```
+
+New behaviour needs tests, and each new runbook feature gets an example runbook in `tests/runbooks/` that shows it off.
+
+If you've changed how runbooks are written or run, update `docs/runbook-format.md` or `docs/cli.md` to match.
+
+Make sure you add to `CHANGELOG.md` and `docs/CHANGELOG.md` what changes you have made. The two must be identical, and a test checks they are.
+
+Make sure you add your name to `CONTRIBUTORS.md` as well!
+
+### Making a pull request
+
+Please push your changes up to a feature branch and make a new [pull request](https://github.com/phalt/rundot/compare) on GitHub.
+
+Please add a description to the PR and some information about why the change is being made.
+
+After a review, you might need to make more changes.
+
+Once accepted, a core contributor will merge your changes!

rundot-0.6.0/CONTRIBUTORS.md

@@ -0,0 +1,3 @@
+# Contributors
+
+- [Paul Hallett](https://github.com/phalt)

rundot-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Hallett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rundot-0.6.0/Makefile

@@ -0,0 +1,49 @@
+help:
+	@echo Developer commands for rundot
+	@echo
+	@grep -E '^[ .a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+
+install:  ## Install requirements ready for development
+	uv sync
+
+deploy-docs:  ## Build and deploy the documentation
+	uv run zensical build --clean --strict
+	uv run ghp-import --no-jekyll --push --force --message "Deploy docs" site
+
+docs-serve:  ## Run a local documentation server
+	uv run zensical serve
+
+release:  ## Build a new version and release it
+	uv build
+	uv publish
+
+ty: ## Run a static syntax check
+	uv run ty check .
+
+lint-imports: ## Check the import contracts in pyproject.toml
+	uv run lint-imports
+
+format: ## Format the code correctly
+	uv run ruff format .
+	uv run ruff check --fix .
+
+clean:  ## Clear any cache files and test files
+	rm -rf .ty_cache
+	rm -rf .pytest_cache
+	rm -rf .ruff_cache
+	rm -rf .import_linter_cache
+	rm -rf site/
+	rm -rf dist/
+	find rundot tests -name __pycache__ -prune -exec rm -rf {} +
+	rm -rf htmlcov/
+	rm -rf .coverage
+
+test:  ## Run tests
+	uv run pytest -vvv -x --cov=rundot --cov-report=term-missing --cov-report=html --cov-config=pyproject.toml
+
+test-quiet: ## Quiet output of tests
+	uv run pytest -x --cov=rundot --cov-report=term-missing --cov-report=html --cov-config=pyproject.toml
+
+shell:  ## Run an ipython shell
+	uv run ipython

rundot-0.6.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: rundot
+Version: 0.6.0
+Summary: Run hand-written markdown runbooks
+Project-URL: Homepage, https://github.com/phalt/rundot
+Project-URL: Documentation, https://docs.rundot.dev/
+Project-URL: Issues, https://github.com/phalt/rundot/issues
+Author-email: Paul Hallett <paulandrewhallett@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: click>=8.5.0
+Requires-Dist: markdown-it-py>=4.2.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Description-Content-Type: text/markdown
+
+# 🏃‍♂️‍➡️📕 rundot
+
+## What is rundot?
+
+rundot executes the code blocks in your markdown file, turning them into runbooks.
+
+A runbook is just a normal markdown file that a person can read and write, but if you annotate a code block `run`, then rundot can execute the code blocks for you, helping you to automate tedious multi-step tasks.
+
+[![Package version](https://img.shields.io/pypi/v/rundot?color=%2334D058&label=latest%20version)](https://pypi.org/project/rundot)
+![Python versions](https://img.shields.io/badge/python-3.12+-blue)
+![PyPI - License](https://img.shields.io/pypi/l/rundot)
+
+## Example runbook
+
+Save this as `hello.md`:
+
+````markdown
+---
+title: Say hello
+inputs:
+  - name: NAME
+    description: Who to say hello to
+---
+
+# Say hello
+
+A runbook is just markdown. rundot runs the blocks marked `run`, shows the
+`docstring` ones, and leaves everything else alone, like this paragraph.
+
+## Greet
+
+```docstring
+Saying hello to <NAME>.
+```
+
+```sh run
+echo "Hello, <NAME>!"
+```
+
+## Count the letters
+
+```python run
+import os
+
+name = os.environ["NAME"]
+print(f"{name} has {len(name)} letters")
+```
+````
+
+Check it, then run it:
+
+```sh
+rundot check hello.md
+rundot hello.md
+```
+
+![rundot checking and running hello.md](docs/demo.svg)
+
+The command `check` will validate the formatting of your Markdown file to make sure it will work with Rundot. 
+
+When running a runbook, rundot asks for the inputs, shows the plan, and runs each step in order.
+
+You can run through each step one at a time with `--step` and even show the code that will run with each step with `--show-code`.
+
+## Your runbook library
+
+Keep runbooks you use across projects in `~/runbooks`, and run them by name from anywhere:
+
+```
+$ rundot library
+library: /home/you/runbooks
+rebuild-frontend     Rebuild the frontend
+update-project-deps  Update a project's dependencies
+
+$ cd ~/Projects/website
+$ rundot rebuild-frontend
+```
+
+A book runs in the folder you're in, so one book works for every project. See [Your runbook library](https://docs.rundot.dev/library/).
+
+## Why use rundot?
+
+Release steps get forgotten. Writing them down helps; making the written-down version run itself fixes it.
+
+- **It's just markdown** - A runbook reads like documentation, renders on GitHub, and works fine without rundot.
+- **Check before you run** - `rundot check` finds broken frontmatter, undeclared placeholders and syntax errors.
+- **See what would happen** - `rundot --dry RELEASING.md` shows every command with its inputs filled in, and runs nothing.
+- **Inputs and secrets** - Ask for values once, check them against a pattern, and keep secrets off the screen and out of the log.
+- **Manual steps too** - `confirm` blocks pause for the things only a person can do.
+- **A record of every run** - An optional transcript keeps every command, its output and how it finished.
+- **More than shell** - Shell and Python blocks are built in, and other languages can be added as backends.
+
+## Install
+
+rundot is a command-line tool, so install it on its own rather than into a project:
+
+```sh
+uv tool install rundot
+```
+
+Or with pip:
+
+```sh
+pip install rundot
+```
+
+rundot needs Python 3.12 or later and `bash`, and runs on **macOS and Linux**. Windows isn't supported. It's for runbooks you run yourself, at a terminal; there's no CI mode.
+
+## Getting started
+
+👉 Read the [full documentation](https://docs.rundot.dev/) for the runbook format, every command, and writing your own backend.
+
+See [`examples/`](https://github.com/phalt/rundot/tree/main/examples) for more runbooks, including a real release, and [`PUBLISHING.md`](https://github.com/phalt/rundot/blob/main/PUBLISHING.md) for the runbook rundot releases itself with.
+
+Want to help? See [CONTRIBUTING.md](https://github.com/phalt/rundot/blob/main/CONTRIBUTING.md).