Skip to content

Update command line interface - #3456

Draft
deruyter92 wants to merge 3 commits into
jaap/update-function-signaturesfrom
jaap/update-cli
Draft

Update command line interface#3456
deruyter92 wants to merge 3 commits into
jaap/update-function-signaturesfrom
jaap/update-cli

Conversation

@deruyter92

@deruyter92 deruyter92 commented Aug 19, 2026

Copy link
Copy Markdown
Collaborator

Motivation
The old deeplabcut/cli.py and root dlc.py became stale and outdated as they have not been maintained since version 2.x. With the official deprecation of TensorFlow (see #3382), this is the right moment to re-introduce an updated, PyTorch centric CLI.

In this PR, deeplabcut/cli.py is rewritten as a Typer app whose commands are thin
wrappers around deeplabcut.*. This should facilitate easy maintenance.
Until TensorFlow is fully removed, engine routing (PyTorch vs. TensorFlow) is automatically handled by
the API layer.

Required parameters are explicit CLI arguments; optional ones can be specified via a repeatable --set key=value

Considerations:
Typer seems like the right trade-off between control and automation, being just a thin wrapper around existing API (less risk of drift compared to bare click commands). Currently also still experimenting with alternatives, such as https://cyclopts.readthedocs.io/en/latest/, which focus even more on automation (Also reads docstrings and allows Union types).

image

Base automatically changed from jaap/deprecation-versions-constants to jaap/prepare_tf_deprecation August 20, 2026 14:54
@deruyter92
deruyter92 changed the base branch from jaap/prepare_tf_deprecation to jaap/update-function-signatures August 21, 2026 08:58
The old deeplabcut/cli.py and root dlc.py were unmaintained DLC2-era
tooling: not wired to the installed `dlc` console script (which only
launches the GUI), untested, and train_network/evaluate_network/
analyze_videos bypassed engine selection by importing
pose_estimation_tensorflow directly instead of the public API.

deeplabcut/cli.py is rewritten as a Typer app whose commands are thin
wrappers around deeplabcut.* (the same functions `import deeplabcut as
dlc` exposes), so engine routing (PyTorch vs. TensorFlow) is handled by
the API layer for free. Required parameters are explicit CLI arguments;
optional ones default to an UNSET sentinel and are only forwarded if the
user actually set them, so the CLI never redeclares (and risks drifting
from) the API's own defaults. Every optional parameter, whether or not it
has a named flag, is also reachable via a repeatable `--set key=value`
escape hatch (YAML-typed); supplying the same parameter both ways is a
hard error. Each command's --help lists its --set-only parameters via an
epilog computed from the real function signature, and --set-help prints
the delegate's full docstring, so neither can go stale.

deeplabcut/__main__.py now dispatches: bare `dlc` still launches the GUI
unchanged, while `dlc <command>` (including `dlc --help`) routes to the
new CLI. Root dlc.py becomes a deprecated shim forwarding to the same CLI.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant