Python tasks for humans and AI agents¶

Invoke Toolkit extends Invoke with a richer terminal interface, extended terminal completion and plugin management. It adapts the base library to be Python script PEP723 + uv shebang friendly, adding a new CLI entrypoint called inkt that can auto-install a more comprehensive shell completion. You can still use invoke_toolkit as invoke but most of the quality of life improvements are on the new modalities.

Quickstart¶

1. Install uv installed,
2. Run invoke-toolkit as a tool:

uv tool run invoke-toolkit -x create.script --name tasks.py

Save this complete tasks.py:

from invoke_toolkit import Context, task


@task
def hello(ctx: Context, name: str = "toolkit") -> None:
    """Greet a person or automation client."""
    print(f"Hello, {name}!")

uv run intk --list
uv run intk hello --name toolkit

Installation choices · Complete quickstart · From Invoke

For humans: discoverable terminal workflows¶

• Rich output and status: styled messages and status spinners, with an optional live panel for the last three subprocess output lines (#105).
• Shell completion: bash, zsh and fish installation; typed choices, paths and callbacks using loaded configuration (#64, #101, #139).
• Interactive selection: fzf when available, a simpler Rich numbered selector otherwise (#80).
• Helpful typo errors: close task names, aliases and nested namespaces are suggested without running a replacement task (#140).

Choose the human workflow.

PEP 723: the portable bridge¶

A task file can carry its own dependency metadata. uv creates the script environment, and Toolkit's script() exposes the tasks as a familiar command interface. Send the same file to an operator, use it in CI, or let an agent discover its commands.

Save this as portable_tasks.py:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = ["invoke-toolkit"]
# ///
from invoke_toolkit import Context, script, task


@task
def hello(ctx: Context, name: str = "toolkit") -> None:
    """Greet from a standalone task file."""
    print(f"Hello, {name}!")


if __name__ == "__main__":
    script()

uv run --script portable_tasks.py hello --name PEP723
uv run --script portable_tasks.py --list --list-format json

uv's inline script environment does not include the surrounding project's dependencies. Toolkit project configuration is a separate concern: script() loads it from the current working directory (#104). Dependency isolation is not a sandbox: imports and tasks still execute Python code with the caller's permissions.

In a Git-managed file, --list-changed shows new or updated definitions compared with HEAD, including staged and unstaged edits. New files and repositories without commits count as new; helpers, globals and imported tasks are outside the comparison (#146).

Read the PEP 723 guide for runnable scripts, configuration, locking and Git-aware discovery.

For AI agents: explicit command contracts¶

Discover with --list --list-format json, inspect each task's help, then run only the intended task with explicit arguments. Authors can reserve stdout for JSON results and stderr for diagnostics.

uv run intk --list --list-format json
uv run intk --help hello
uv run intk --disable-status hello --name agent

JSON discovery is not universal JSON output. Task code owns execution output, and help/listing import modules and execute their top-level statements. Toolkit does not provide an MCP server, a sandbox or permission enforcement.

Agent workflow · Existing task-authoring skill (#110)

Go deeper with the library¶

CLI reference · Public API reference · Troubleshooting · Complete merged-PR improvement map

These guides describe current main; a previously installed release may lag recently merged changes. Runtime support is Python 3.10+, Invoke 3.0.3+ and Rich 13+ (#114). See installation for release and source-checkout workflows.