Skip to content

User Guide

📖 invoke-tasklib groups its tasks into namespaces, one per module. Each namespace maps to one page in this guide.

All Tasks at a Glance

Each task either checks/reports (read-only, exits non-zero on violations) or mutates (formats, builds, publishes) — the Mutates? column below flags which.

Namespace Task Behavior Mutates?
Format format.check-python Check Python formatting with ruff ❌
Format format.fix-python Format Python code with ruff ✅
Format format.check-docstrings Check docstring formatting with docformatter ❌
Format format.fix-docstrings Format docstrings with docformatter ✅
Format format.check-shell Check shell scripts with shellcheck ❌
Format format.check-shell-format Check the format of shell scripts with shfmt ❌
Format format.fix-shell Format shell scripts with shfmt ✅
Lint lint.check-python Check code linting with ruff ❌
Lint lint.fix-python Fix auto-fixable linting issues with ruff ✅
Lint lint.check-spelling Check the spelling with codespell ❌
Lint lint.pre-commit Run all the pre-commit hooks ✅
Imports imports.check-cycles Check for cyclic import dependencies ❌
Imports imports.check-isolated Check that every module imports on its own ❌
Types types.check Check type hints with ty (--complete: + pyright) ❌
Test test.doctest Run doctests on source code and markdown files ❌
Test test.doctest-src Run doctests on source code ❌
Test test.doctest-markdown Run doctests on Python examples in markdown ❌
Test test.unit Run unit tests ❌
Test test.integration Run integration tests ❌
Test test.functional Run functional tests ❌
Test test.all Run unit, integration, and functional tests ❌
Test test.coverage-report Generate an HTML/terminal report from coverage data ❌
Test test.benchmark Run performance benchmarks ❌
Env env.create-venv Create a virtual environment and install the project ✅
Env env.install Install project dependencies and the package ✅
Env env.check-tools Check which tools are available ❌
Env env.update Update dependencies and pre-commit hooks ✅
Env env.show-installed-packages Show installed packages ❌
Env env.show-python-config Show the Python configuration ❌
Release release.build Build the package and verify installation ✅
Release release.publish Build and publish the package to PyPI ✅
Doc doc.build Build the docs, failing on warnings ❌
Doc doc.serve Serve the docs locally ❌
Doc doc.publish-dev Publish development (unstable) docs ✅
Doc doc.publish-latest Publish latest (stable) docs ✅
Security security.audit Audit dependencies for known vulnerabilities ❌
Check check.all (or check) Run the main read-only checks ❌
Fix fix.all (or fix) Fix the lint and format issues ✅
Clean clean.all (or clean) Remove build artifacts and caches ✅
Clean clean.pycache Remove all __pycache__ directories ✅
Config config.show Show the resolved config and its origins ❌
Config (none — shared config) Config resolution used by all tasks above —

Everyday Workflow

A typical local development loop looks like this:

invoke format.fix-python format.fix-docstrings   # auto-fix formatting
invoke lint.check-python imports.check-cycles types.check  # check quality
invoke test.unit --cov                            # run tests with coverage

To run the main read-only checks (format, lint, types, imports and the unit tests) in one command:

invoke check

See Check for the steps and the options.

And what CI typically runs (nothing should modify the working tree):

invoke format.check-python format.check-docstrings lint.check-python imports.check-cycles types.check
invoke test.all --cov

Since Invoke lets you chain multiple task names in one command, all of the above run as a single invoke call each.

Passing Arguments to the Tools

Every task that runs an external tool takes --args, and the tasks that run on files also take --paths:

  • --args adds arguments to the command. The value is one string, split like a shell does.
  • --paths runs the tool on these files or directories instead of the default ones (the project for ruff, paths.src for docformatter and the source doctests, the scope directory for pytest, every *.sh file for shellcheck and shfmt, every markdown file for the markdown doctests). The value is quoted, so a glob (src/*.py) or ~ reaches the tool as it is: only a tool that expands globs itself (like ruff) handles them.
Tasks --args goes to --paths
test.all, test.unit, test.integration, test.functional, test.benchmark pytest ✅
test.doctest-src pytest ✅
test.doctest-markdown python -m doctest ✅
test.coverage-report coverage report ❌
format.*-python, lint.check-python, lint.fix-python ruff ✅
format.*-docstrings docformatter ✅
format.check-shell, format.check-shell-format, format.fix-shell shellcheck, shfmt ✅
lint.check-spelling codespell ✅
lint.pre-commit pre-commit ❌
types.check ty (only) ✅
security.audit pip-audit ❌
doc.build, doc.serve mkdocs ❌
release.build uv build ❌
release.publish uv publish ❌

The other tasks have no --args: the composite tasks (check.all and fix.all with --only, --skip and --keep-going, test.doctest), the tasks that run no external tool (clean.*, imports.*, config.show) and the tasks with their own options (env.*, doc.publish-*).

invoke test.unit --args "-k foo -x" --paths tests/unit/test_foo.py
invoke lint.check-python --args "--select E" --paths "src/a.py src/b.py"
invoke format.check-python --paths src/a.py
invoke security.audit --args "--ignore-vuln PYSEC-2024-1"
invoke doc.serve --args "--dev-addr 127.0.0.1:8001"
invoke test.coverage-report --args "--fail-under=90"

For types.check, --args goes to ty only and --paths goes to ty and pyright. The arguments and the paths are quoted, so they are never interpreted by the shell.

Missing Paths

One rule says what a task does when a path of the config does not exist:

Kind of path When it is missing Examples
A directory the task may legitimately not have ⏭️ message naming the directory, exit code 0 paths.unit_tests, paths.integration_tests, paths.functional_tests
A path the task is about Exit code 2, the message names the key paths.src (test.doctest-src, format.*-docstrings), paths.docs_config
The only input of a task that produces a measurement Exit code 1 paths.benchmarks (test.benchmark)

A path given with --paths is never checked by the task: the tool reports it. In check.all a skipped directory is a skipped step, not a failure.

External Tools

Tasks are thin wrappers around external command-line tools. Each is expected to be available on PATH or next to the Python interpreter that runs invoke (or installed via env.install/env.create-venv):

Tool Used by
ruff format.check-python, format.fix-python, lint.check-python
docformatter format.check-docstrings, format.fix-docstrings
shellcheck format.check-shell
shfmt format.check-shell-format, format.fix-shell
ty types.check
pyright types.check --complete
pytest test.* except test.doctest and test.doctest-markdown
pytest-timeout test.unit, test.integration, test.functional, test.all
pytest-cov the --cov option of the test.* tasks
coverage test.coverage-report
xdoctest test.* (unless tasklib.test.xdoctest is false), test.doctest-src
pytest-benchmark test.benchmark
uv env.* (except env.check-tools), release.*, security.audit
twine (via uvx) release.build --check
codespell lint.check-spelling
pre-commit lint.pre-commit
mkdocs doc.build, doc.serve
mkdocs-material the theme of the docs built by doc.build, doc.serve
mike doc.publish-dev, doc.publish-latest
git doc.publish-latest, release.publish, and the file lookup of the shell and markdown tasks
pip-audit (via uvx) security.audit

Most of these come from your project's own dev/docs dependency groups; see Env for how env.install wires them up, and the Troubleshooting guide if a task fails with a "command not found" error.

See Also