Installation¶

Invoke Toolkit is both a Python library and a CLI. Choose an environment that contains the tasks' imports and any plugins you intend to discover.

As a tool¶

uv tool install invoke-toolkit[full]

Compatibility and release scope¶

The runtime requires Python 3.10+, Invoke 3.0.3+ and Rich 13+. The Invoke 3 compatibility cutover is documented in PR #114. The documentation build toolchain separately needs Python 3.11+; it does not raise the library's runtime floor.

These pages describe the source on current main. A previously installed PyPI release may not contain all recently merged changes. Check your installation with:

intk --version

Use the improvement history to find the originating changes, and the source-checkout option below when you need current-main behavior.

Add the library to a project¶

With uv and an existing pyproject.toml:

uv add invoke-toolkit
uv run intk --version

For a new project, initialize it first:

uv init toolkit-demo
cd toolkit-demo
uv add invoke-toolkit

Or install in an activated virtual environment using pip:

python -m pip install invoke-toolkit
intk --version

The package exposes intk, invoke-toolkit and inv, all pointing at Toolkit's program. intk is used throughout these guides to avoid ambiguity with upstream Invoke installations. Be aware that both packages expose an inv command; which one your shell finds depends on the environment and PATH.

Continue with the quickstart.

Install a persistent CLI tool¶

For a CLI on your PATH with its own environment:

uv tool install invoke-toolkit
intk --version

pipx is another option:

pipx install invoke-toolkit
intk --version

A tool environment does not automatically contain your project's Python dependencies. If a task imports a project-specific package, install that dependency in the tool environment or run Toolkit inside the project instead.

Reusable plugins are discovered from the environment running Toolkit. Built-in plugin.add, plugin.link, plugin.remove, plugin.list and plugin.update lifecycle commands require a persistent uv tool install environment. They reject transient uvx, project uv run and other installers; entry-point discovery is a separate feature (PR #138). See the plugins guide.

Use a portable script instead¶

You do not need to install a global CLI to run a PEP 723 task file:

uv run --script portable_tasks.py --list

Create portable_tasks.py using the complete example in the PEP 723 guide. uv reads the file's inline dependency metadata and prepares its environment. When that metadata is present, uv ignores the surrounding project's dependencies; declare all script imports in the metadata.

Optional dependencies¶

Quote extras in shells that interpret square brackets:

uv add 'invoke-toolkit[cache]'

For a persistent tool environment with both cache and templating support:

uv tool install 'invoke-toolkit[cache,copier]'

Without diskcache, decorated callbacks and tasks can execute but do not get persistent caching. See caching. fzf is an external executable, not a Python extra; interactive selection describes its reduced Rich fallback.

Work from current source¶

Clone a Git checkout so Git-derived version metadata is available:

git clone https://github.com/D3f0/invoke-toolkit.git
cd invoke-toolkit
uv sync
uv run intk --version

For source installed in a separate activated virtual environment, from the cloned repository:

python -m pip install -e .
intk --version

Source-checkout execution is useful for checking current-main documentation. It is not the persistent uv tool environment required by plugin lifecycle commands. See CONTRIBUTING for the full development and documentation workflow.

Next steps¶

• Write your first task.
• Migrate an Invoke task collection.
• Install shell completion.
• Choose a portable PEP 723 file.
• Troubleshoot environments and discovery.