Add unified dissect command entry point

[yunzheng]

This PR adds a single dissect command that dispatches to the various target-* tools as describe in #104, so they can be run without installing/knowing each script name:

$ uvx dissect shell <target>      ->  target-shell <target>
$ uvx --pre dissect dd <target>   ->  target-dd <target>

$ dissect --help
 usage: dissect [-h] <command> ...

 Unified entry point for the dissect target-* tools.

 positional arguments:
   <command>
     shell             run target-shell
     dd                run target-dd
     ...

DISCLAIMER: Claude made this using my prompts, the pyproject.toml and tox.ini fixups were done manually.

• Closes Add support for uvx dissect #104
• Related: Rename CLI Plugins to make the names more inline with the whole project dissect.target#1641
• Related: Add dissect- prefixed aliases to all script entry points #105

Changes

• New dissect/cli.py dispatcher exposed via [project.scripts] as dissect = "dissect.cli:main".
• Subcommands are discovered dynamically from the console_scripts entry points (any target-<name> becomes dissect <name>), so the list stays in sync automatically.
• Uses argparse with subparsers for a proper --help/command listing and clean error handling, then forwards the remaining args to the underlying tool verbatim (sidestepping the argparse.REMAINDER leading-option bug).
• Subcommand help uses each tool's module docstring summary, extracted statically via ast (no import, no side effects). Falls back to run target-<name> when a tool has no docstring.
• pyproject.toml: enabled namespace package discovery (namespaces = true, include = ["dissect", "dissect.*"]) so dissect/cli.py is packaged while keeping dissect a PEP 420 namespace package (no __init__.py).

Notes

Currently we should add a one-line module docstring to the target-* tools in dissect.target, which would make the dissect --help listing more descriptive. They now fall back to a generic string, which is: run target-<name>.

[yunzheng]

This does not solve:

• Add dissect- prefixed aliases to all script entry points #105

Because this tool dump-nskeyedarchiver lives in dissect.util. However we could add that I guess? Same applies for possible other tools/entrypoints that can be discovered dynamically.

UPDATE: is now discoverable via --help-all in commit below.

[yunzheng]

Added a new commit that adds the following improvements to the unified dissect cli:

• Added a --help-all option, which lists ALL commands in the dissect.* namespace.
• --help will only list the target commands.
• Added fast-path, meaning that the CLI has minimal imports if we directly specify a <command> to run to reduce startup time. Only when --help or --help-all is specified the parser is built using importlib and ast.
• Added benchmarks to keep track of startup times over time and ensure fast-path keeps fast.

Some screenshots below for comparison and tracking progress over time (click to open):

screenshot of previous `dissect --help`

screenshot of `dissect --help`

screenshot of `dissect --help-all`

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[codspeed]

Congrats! CodSpeed is installed 🎉

🆕 12 new benchmarks were detected.

You will start to see performance impacts in the reports once the benchmarks are run from your default branch.

Detected benchmarks

• test_benchmark_build_help: 128.5 ms
• test_benchmark_dispatch_module: 24.5 µs
• test_benchmark_find_command: 10.2 ms
• test_benchmark_iter_commands: 10.2 ms
• test_benchmark_main_fast_path: 133.7 µs
• test_benchmark_main_help: 129 ms
• test_benchmark_main_help_all: 314.2 ms
• test_benchmark_main_missing_sibling: 10.2 ms
• test_benchmark_main_unknown_command: 12.2 ms
• test_benchmark_read_console_script: 106.1 µs
• test_benchmark_resolve_sibling: 130 µs
• test_benchmark_resolve_sibling_miss: 75.3 µs

---

[Copilot]

🟢 Approval recommended

The reviewed changes are covered by tests and CI updates with no unresolved blocking issues.

Pull request overview

Adds a unified dissect CLI that dynamically discovers and dispatches installed target tools.

Changes:

• Added CLI dispatcher and console entry point.
• Added dynamic command discovery, help generation, and argument forwarding.
• Added tests, benchmarking, lint configuration, and CI coverage.
• Updated namespace package discovery.

File summaries

File	Description
tox.ini	Adds benchmark, lint, and formatting environments.
tests/test_cli.py	Adds functional and benchmark tests.
tests/conftest.py	Handles optional benchmark dependencies.
tests/__init__.py	Adds the tests package marker.
pyproject.toml	Registers the CLI and configures package discovery.
dissect/cli.py	Implements command discovery, dispatch, and help generation.
.github/workflows/dissect-ci.yml	Enables linting, tests, and benchmarks.

Review details

• Files reviewed: 6/7 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.