nur

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

Run nur in a project and it discovers the tasks your project already defines — from npm, Make, deno, composer, just, Taskfile, PDM/poe, mise, cargo-make, moon, and xc — then lets you run them from a TUI picker or directly from the command line. Discovery is limited to the current directory. See Features for the full list of source files.

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

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

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 twelve providers, each parsed from a single source file in the current directory:

  Provider	Prefix	Source file
  npm	npm	package.json
  deno	deno	deno.json / deno.jsonc
  composer	composer	composer.json
  Make	make	Makefile
  PDM	pdm	pyproject.toml ([tool.pdm.scripts])
  poe	poe	pyproject.toml ([tool.poe.tasks])
  just	just	justfile
  Taskfile	task	Taskfile.yml
  mise	mise	mise.toml (and variants — see below)
  cargo-make	cargo-make	Makefile.toml
  moon	moon	moon.yml
  xc	xc	README.md (see below)

  mise reads the first config file present, in priority order: mise.local.toml, mise.toml, .mise.local.toml, .mise.toml, .config/mise.toml. xc reads its task section from README.md — the block marked with an <!-- xc-heading --> comment, or failing that a heading named Tasks (which is how nur discovers the tasks documented in this very file). composer reads the top-level scripts object from composer.json, surfacing only user-defined custom scripts (Composer's reserved lifecycle hooks like post-install-cmd are filtered out) and taking descriptions from the scripts-descriptions table when present.

• 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.