cli-maintenance

CLI Maintenance

When to use this skill

• Adding a new subcommand to the CLI
• Changing args/behavior of an existing command
• Removing or renaming a command
• Responding to a cli-plugin-sync hook reminder
• Auditing CLI / plugin / docs consistency

Doctor gating: separate capability-to-BUILD from capability-to-PUBLISH

DoctorCheck carries two independent flags, and picking the wrong one has opposite failure modes:

• optional — advisory everywhere, including pulp doctor's exit code. For things that are a speedup, not a requirement (e.g. the Google Android CLI accelerator).
• release_only — still gates pulp doctor, but must NOT gate commands that merely build or scaffold. For credentials and capabilities needed to PUBLISH.

RELEASE_BOT_TOKEN is the worked example. It was neither flag, so it gated pulp create, which then refused to scaffold a project on any machine lacking the secret — every contributor's, since a repo secret is not theirs to set, and every fleet host that is not the release host. The error printed a PAT walkthrough to people who were only trying to create a project.

Do not "fix" this class by marking such a check optional. That silences it in pulp doctor too, and the release-readiness signal is load-bearing: a missing RELEASE_BOT_TOKEN once caused a 22-hour release drought. Add release_only and let the consuming command decide, as cmd_create.cpp does:

if (c.optional || c.release_only) { /* advisory: print, do not gate */ }

Equally, do not fix it by configuring the secret on more hosts — that makes the test pass without making the behaviour correct, and spreads a release credential to machines with no use for it.

Doctor's environment checks live in C++, not in the Rust CLI

There are two doctor implementations and only one of them runs checks. The Rust cmd::doctor::run (experimental/pulp-rs/src/cmd/doctor.rs) is native only for --versions --json; every other lane — the default check list included — falls through to pulp-cpp. The checks themselves are in tools/cli/cli_doctor_helpers.cpp (run_doctor_checks), not in tools/cli/cmd_doctor.cpp, which owns argument parsing and rendering.