CLI & Task Contract
Runner Model & CLI Contract
Discovery rules, typed task parameters, CLI path resolution, dependency validation, and exit codes.
This specification defines the normative M1–M4 contract shared by tasknest-py and tasknest-ts.
Discovery and Registration
- One task per file: Each discovered non-underscore source file under a
[[discovery.roots]]entry must register exactly one task (0or> 1raises a discovery error). - Tier 1 manifest tasks:
package.json("scripts"/"tasknest") andpyproject.toml([tool.tasknest.tasks]) discovered via[discovery].workspacesor[[discovery.manifests]]load before[[discovery.roots]]; file tasks with the same canonical name override manifest tasks (Manifest Tasks & Packages). - Exclusions: Files or directories starting with
_(such as_helpers.py,__init__.py) and top-leveltests/andfeatures/folders directly under a discovery root are ignored. - Canonical names & CLI paths:
check/dev.pymaps to canonical namecheck.devand CLI pathcheck dev(prefixed bynamespaceif configured). Duplicate canonical names across file roots fail discovery.
Trusted Code
Discovery imports task modules and executes top-level code. Discovery is not a sandbox; run Tasknest only on trusted repositories.
Typed Task Parameters
- Python derives CLI flags from type annotations (
str,int,float,bool,Path,T | None,Literal[...],list[T]). - TypeScript derives CLI flags from the
optionsarray ("string","int","float","boolean","path",choices,multiple,optional,default). - Snake-case parameter names map to kebab-case flags (
dry_run→--dry-run); booleans accept--flagand--no-flag.
CLI Grammar & Disambiguation
tasknest [GLOBAL OPTIONS] <command> [ARGS...]- Global options (before subcommand only):
--root <path>,--config <path>,-v/--verbose,-h/--help,--version. - Subcommands:
ls [--mark <name>] [-p|--package <pkg>]— List discovered tasks.help [task...]— Show global or task help.check— Validate discovery, parameters, marks, and dependency cycles without running tasks.plan [--mark <name> | --each <task> | <task...>] [-p|--package <pkg>]— Print execution order and declared effects.run [RUN FLAGS] [--mark <name> | --each <task> | <task...>] [-p|--package <pkg>] [task args...]— Execute tasks.watch [WATCH FLAGS] <task...>— Watch declaredinputsand re-run dirty subgraph.skill [--check | --write [--force]]— Verify or write generatedSKILL.md.
- Longest-prefix resolution: Non-flag tokens match the longest registered task path; use
--to disambiguate positional arguments (e.g.tasknest run a -- bpassesbpositionally toaeven whena.bexists).
Exit Codes
| Exit Code | Meaning |
|---|---|
0 | Success |
1 | Task execution / runtime failure |
2 | CLI usage, config, discovery, validation, or dependency graph error |