Skip to main content

invoke-toolkit

A set of extensions for rich output, more options in collection/config discovery through entry-points.

This extends the Collection from Invoke so it can create automatically collections.

PyPI - Version PyPI - Python Version


Table of Contents

Features

  • Task discovery by namespace for extendable/composable CLIs
  • Discovery to plain old tasks.py (or any other name)
  • Local tasks discovery from local_tasks.py in the current directory
  • Integration with stand alone binaries for specific tasks
  • Task result caching with TTL support via diskcache (optional)
  • Future Download binaries

Do I need this package

If you have...

  • Used invoke for a while and...
  • Have a large tasks.py that needs to be modularized
  • Have a lot of copy/pasted code in multiple tasks.py across multiple repos.
  • Have exceeded the approach of a repository cloned as ~/tasks/ with more .py files that you want to manage.
  • Or you want to combine various tasks defined in multiple directories
  • You want to create a zipped (shiv) redistribute script for container environments like Kubernetes based CI environments with only requiring the Python interpreter.

Installation

pip install invoke-toolkit

Quick Start

Using Local Tasks

Create a local_tasks.py file in your project directory with your tasks:

from invoke_toolkit import task

@task()
def my_task(ctx):
    """Do something useful"""
    print("Hello from local tasks!")

Then run it with:

intk local.my-task

Local tasks are automatically discovered and added to the local namespace, allowing you to keep project-specific tasks separate from your main task collection.

Listing changed tasks

For a Git-managed PEP 723 script that calls invoke_toolkit.script():

uv run tasks.py --list-changed
uv run tasks.py --list-changed --list-format json
uv run tasks.py --list

--list-changed lists only new or updated task definitions compared with Git HEAD, including staged and unstaged edits. Normal flat and nested listings also highlight new tasks in green and updated tasks in yellow. Color follows Rich's terminal detection and NO_COLOR; JSON retains Invoke's existing schema. The flag also works with intk --list-changed for a loaded task file, and can combine with --list <namespace>, --list-tasks, or --list-plugins to narrow the listing further.

Comparison includes task bodies, signatures, decorators, and docstrings, but ignores comments, formatting, and line-number shifts. Imported tasks and indirect changes through helpers or globals are not included. Historical source is parsed, never executed. In a Git repository, every task in a file absent from HEAD (including a new repository without commits) counts as new. Adding a task decorator to a helper counts as new; changing the decorator's explicit task name counts as an update to that existing definition.

With no changes, the flag exits successfully with an empty JSON task list or a message for human-readable formats. Outside a Git repository, or without Git, --list-changed reports an error; normal listing still works without highlights.

Using Task Caching

Cache expensive task results with the cache parameter:

from invoke_toolkit import task

# Simple caching (no expiration)
@task(cache=True)
def expensive_task(ctx, param: str) -> str:
    """Results are cached across invocations."""
    return do_expensive_computation(param)

# Caching with TTL (1 hour)
@task(cache={"ttl": 3600})
def cached_task(ctx, name: str) -> dict:
    """Results cached for 1 hour."""
    return fetch_data(name)

# Caching with ignored arguments
@task(cache={"ttl": 600, "ignore_args": ["verbose"]})
def cached_with_options(ctx, query: str, verbose: bool = False) -> list:
    """Cache key ignores verbose flag."""
    return search(query, verbose=verbose)

Cache features:

  • Cache location is computed from git repository root + platformdirs
  • Debug logging (-d flag) shows cache hits/misses
  • Graceful degradation when diskcache is not installed

To enable caching, install with the cache extra:

pip install invoke-toolkit[cache]

Dynamic task defaults

Use Field when an argument default must be computed from the final task context or resolved from a URI. Explicit command-line values always take precedence.

Bind a resolver once, then reuse the resulting callable for scalar and file defaults. A local resolver always returns one string value per request. The resolver receives every URI using that callback and scheme in one batch.

from invoke_toolkit import Context, Field, FilePath, task


def resolve_bw(ctx: Context, requests: list) -> dict[str, str]:
    return {
        request.parameter: ctx.run("bw get password ...", hide=True).stdout.strip()
        for request in requests
    }


BitwardenField = Field(resolver=resolve_bw)
ExistingFile = FilePath(exists=True, dir_okay=False)


@task
def deploy(
    ctx: Context,
    password: str = BitwardenField(default="bw://PASSWORD_ID"),
    config: ExistingFile = BitwardenField(
        default="bw://CONFIG_ID", cleanup="task"
    ),
) -> None:
    ...

For str fields, the resolver string reaches the task unchanged. For Path or FilePath fields, Field.create_temporary_file() writes that string to a managed temporary file and passes its Path to the task. Override that method in a Field subclass to control file creation; resolvers do not return paths.

For omitted arguments, lookup precedence is explicit CLI/Python/call value, then INVOKE_<PARAMETER> environment value, then the resolved ctx.config value, then the declared Field default or factory. URI values from config use the same local or entry-point resolver dispatch as declared URI defaults.

Field(default_factory=callback) runs only if no higher-precedence value is available. Factories and resolvers never run during help, listing, or shell completion; Path/FilePath completion continues to work normally for explicit values.

Temporary Path files from resolver-bound Field instances are owned by invoke-toolkit. cleanup="pipeline" is the default and keeps the file through expanded pre/main/post execution; cleanup="task" removes it when that task returns. Cleanup runs after failures and cancellation.

Installed invoke_toolkit.field_resolver entry points remain supported for compatibility but issue a warning recommending a task-local resolver. Generate a resolver-only provider package with:

intk -x create.package --provider op

Provider packages expose no task collection. Providers return text only; for Path fields invoke-toolkit materializes and cleans the resulting temporary file according to that Field's cleanup lifetime.

uv tool plugins

Plugin management requires a persistent uv tool install invoke-toolkit environment. Plugins are distributions that expose an invoke_toolkit.collection entry point; their package names do not need an invoke-toolkit- prefix.

intk -x plugin.list
intk -x plugin.add 'invoke-toolkit-example>=1'
intk -x plugin.add git+https://github.com/example/invoke-toolkit-example.git
intk -x plugin.add ./invoke-toolkit-example
intk -x plugin.link ./invoke-toolkit-example
intk -x plugin.update --name invoke-toolkit-example
intk -x plugin.update
intk -x plugin.remove invoke-toolkit-example

plugin.add uses uv's --with mode. A local directory is built as a static installation. plugin.link uses --with-editable, so source changes are live. A named update refreshes one non-editable plugin; an update without a name refreshes all non-editable plugins and reports linked plugins as skipped. Registry constraints and pinned Git references remain in effect. Plugin updates do not update invoke-toolkit itself. Shell completion suggests directly installed plugin names for plugin.remove and named plugin.update operations.

To reduce shell-completion latency in environments with expensive collection plugins, set completion.disable_plugins: true in invoke.yaml:

completion:
  disable_plugins: true

INVOKE_COMPLETION_DISABLE_PLUGINS=1 enables the same behavior without changing the configuration file. Completion then skips installed invoke_toolkit.collection entry points while retaining project, local, and built-in -x task suggestions. These settings affect completion only; normal task execution and listing still load plugins.

These commands reject uvx, uv run, project environments, and installations managed by another tool. pipx offers a similar manual workflow:

pipx inject invoke-toolkit PLUGIN
pipx inject invoke-toolkit --editable ./PLUGIN
pipx uninject invoke-toolkit PLUGIN
pipx list --include-injected

pipx accepts registry, local, and Git sources supported by pip. invoke-toolkit does not detect or execute pipx lifecycle operations.

Development

This project utilizes the pre-commit framework, make sure you run:

pre-commit install

With uvx:

uvx --with pre-commit-uv pre-commit install

License

invoke-toolkit is distributed under the terms of the MIT license.

Metadata

Release files for invoke-toolkit 0.0.75

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for invoke-toolkit 0.0.75
File Size Uploaded Provenance Actions
invoke_toolkit-0.0.75.tar.gz 203.5 kB With provenance Details for invoke_toolkit-0.0.75.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for invoke-toolkit 0.0.75
File Interpreter ABI Platform Actions
invoke_toolkit-0.0.75-py3-none-any.whl Python 3 none any Details for invoke_toolkit-0.0.75-py3-none-any.whl

Total release size: 333.6 kB

Release files / invoke_toolkit-0.0.75.tar.gz

Download URL invoke_toolkit-0.0.75.tar.gz
Size 203.5 kB
Tags Source
SHA-256 checksum
How to use checksums
9985d8396516d1c793e9ffd3899d5cb90ff8378045ff0a410d1b98067004236d
BLAKE2b-256 checksum
How to use checksums
6eb5e1c5e43d5cf99cedd63e384cf545f89deedb6af0276423ac9afca30d4aaf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / invoke_toolkit-0.0.75-py3-none-any.whl

Download URL invoke_toolkit-0.0.75-py3-none-any.whl
Size 130.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0dd6ff5dd074997c7da2b11c35119101215a8b013f37d866577db74e0d3bd04a
BLAKE2b-256 checksum
How to use checksums
64a78f6ab0d0bd25a4344cccf386f6041e8fe315009b748c342cc24815fd8ce6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Security for invoke-toolkit 0.0.75

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for invoke_toolkit-0.0.75.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.75 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page