nur

A script discovery and execution engine for your project's tasks.

Run nur in a project and it discovers tasks across npm (package.json), Makefile, PDM/poe (pyproject.toml), justfile, Taskfile.yml, mise (mise.toml), and xc (README.md), then lets you run them from a TUI picker or directly from the command line. Discovery is limited to the current directory.

Table of Contents

• Installation
• Usage
• Support
• Motivation
• Features
• Author
• Analysis
• Contributing
• Development
• Releasing
• Credits
• License
• Changelog

Installation

nur is a standalone command-line tool — install it into an isolated environment rather than as a project dependency:

uv tool install nur

pipx install nur

Or run it without installing:

uvx nur

On macOS/Linux via Homebrew:

brew install hasansezertasan/tap/nur

On Windows via Scoop:

scoop bucket add hasansezertasan https://github.com/hasansezertasan/scoop-bucket
scoop install nur

To install the latest unreleased changes from source:

uv tool install git+https://github.com/hasansezertasan/nur

Or, from a clone:

uv tool install .

Usage

Run nur from the root of a project that contains any supported task file.

TUI

Run with no arguments to open the interactive picker:

nur

Browse and run the discovered tasks in a three-pane Textual UI. Press q to exit.

CLI

nur test            # run a task by name (if unambiguous)
nur make:test       # run a task by its qualified name
nur test -- --watch # pass extra args through to the underlying runner
nur list            # print all discovered tasks
nur --version

Debugging

Debug nur in VS Code using the provided launch configurations:

• Current File: Debug the currently open Python file.
• Tests: Debug pytest runs.
• Attach: Attach to a running process (with debugpy).
• CLI / TUI: Debug the nur entry point — with arguments (CLI) or with none, which opens the TUI.

Select a configuration from the Run and Debug panel in VS Code.

Support :heart:

If you have any questions or need help, feel free to open an issue on the GitHub repository.

Motivation

Every project speaks a different task dialect — make test, npm run test, just test, task test, pdm run test, poe test, mise run test, xc test. nur gives you one command that discovers whatever a project already uses and runs it, with no config and no need to remember which runner lives where. Discovery is pure text/JSON/TOML parsing, so listing tasks never executes anything (no make -pRrq side effects).

Features

• Zero-config discovery across eight providers: make, npm, just, task (Taskfile), pdm, poe, mise, and xc. mise is read from the first config file present, in priority order: mise.local.toml, mise.toml, .mise.local.toml, .mise.toml, .config/mise.toml. xc is read from README.md: tasks come from the section marked with an <!-- xc-heading --> comment, or failing that from a heading named Tasks — which is how nur discovers the tasks documented below in this very file.
• CLI Application: run any discovered task by name or qualified prefix:name, with -- passthrough to the underlying runner.
• TUI Application: interactive three-pane task picker built with Textual.
• Safe by default: discovery parses files; it never shells out to a runner just to list tasks.
• Type Safety: full type hints checked by mypy, basedpyright, ty, pyrefly, and zuban.
• Code Quality: comprehensive linting and formatting with ruff, plus architecture-contract enforcement with import-linter.
• Testing: pytest with coverage reporting and parallel execution.
• Documentation: Sphinx documentation with the Shibuya theme, GitHub Pages deployment, and live per-PR documentation previews.
• CI/CD: automated testing, building, and publishing across multiple platforms.
• Security: CodeQL, OpenSSF Scorecard, dependency review, secret scanning (gitleaks), dependency auditing (pip-audit), GitHub Actions static analysis (zizmor — a blocking prek/CI gate plus a Security-tab dashboard, over hardened least-privilege workflows), and a CycloneDX SBOM attached to every release.
• Managed .gitignore: kept in sync with the upstream github/gitignore templates by cobo, with a weekly drift check.
• Modern Python: uv for dependency management, hatch for building.

Author :person_with_crown:

This project is maintained by Hasan Sezer Taşan, It's me :wave:

Analysis

• Snyk Python Package Health Analysis
• Libraries.io - PyPI
• Safety DB
• PePy Download Stats
• PyPI Download Stats
• Pip Trends Download Stats
• PyPI Map Dependency Graph

Contributing :heart:

Any contributions are welcome! Please follow the Contributing Guidelines to contribute to this project.

Development :toolbox:

Clone the repository and cd into the project directory:

git clone https://github.com/hasansezertasan/nur
cd nur

install

Install the dependencies:

uv sync

style

Run the style checks:

uv run --locked tox run -e style

ci

Run the CI pipeline:

uv run --locked tox run

docs-build

Build the documentation site:

uv run --locked tox run -e docs-build

docs-server

Start the live-reloading docs server:

uv run --locked tox run -e docs-server

docs-linkcheck

Check the documentation for broken links (also runs weekly in CI):

uv run --locked tox run -e docs-linkcheck

Releasing

Versioning and releases are automated with release-please, driven by Conventional Commit PR titles squash-merged into main. release-please maintains a release PR that bumps the version and CHANGELOG.md; merging it tags the release and publishes to PyPI. See the Contributing Guidelines for the commit conventions and the one-time Repository setup (squash-merge settings, Actions permissions, release immutability, and PyPI trusted publishing).

Credits

This package was created with Copier and the hasansezertasan/copier-pyproject project template.

License :scroll:

This project is licensed under the MIT License.

Changelog :memo:

For a detailed list of changes, see the GitHub Releases. A CHANGELOG.md is generated automatically by release-please on each release.