[celanthe]

What changed

• scripts/cli-drift-check.py (Python standard library only) runs the CLI's hidden docs generate command, reads each command's aliases from --help, and checks every Markdown file under orka3-cli/:
  • Errors: a ## orka3 <command> heading, an example command, an example flag, or an Options list entry that the CLI doesn't have.
  • Warnings: a CLI flag that a command reference's **Options:** list leaves out. These fail only with --strict.
  • Example lines are code-block lines that start with orka3 or orka, including inside $(...), after a pipe, &&, or ;, with \ continuations joined. Aliases such as sa, rb, ic, vmc, and regcred resolve to their commands.
  • Commands marked "Removed in Orka X" or "Deprecated in Orka X" in their section or ## group intro are skipped, since Cobra hides deprecated commands from the generated help.
  • --binary-name orka|orka3 sets which CLI name is being checked (default: read from the generated help). Against a 4.x orka CLI, orka3 lines and headings are treated as 3.x-only and skipped. Against a 3.x CLI, orka lines are skipped. The summary reports how many were skipped.
• .github/workflows/cli-drift-check.yml runs on pull requests that touch orka3-cli/** (or the check itself), every Monday, and on workflow_dispatch with an optional cli_version override. It downloads the Linux CLI from cli-builds-public the same way macstadium-docs#422 does. Findings show as PR annotations and in the job summary.
• CONTRIBUTING.md has a short section on running the check locally and the conventions it relies on.

Why

Customers' agents ran emulator flags that don't exist (--device, --cpu, --memory, emulator list --vm), because the skill documented them and nothing compared the skill with the CLI. This mirrors macstadium-docs#422, which does the same for the docs site's CLI reference pages, and reuses its approach: download the released CLI for a CLI_VERSION, generate the help, and compare.

Tested

Ran locally against origin/main with the macOS arm64 builds from cli-builds-public (expanded with pkgutil, not installed). 26 files, 521 example commands.

CLI	Commands in CLI	Errors	Warnings
3.7.0-alpha (workflow default)	90	15	14
3.6.4	86	22	9

Errors against 3.7.0-alpha:

Where	Finding
SKILL.md:88, emulator-commands.md:35,36,37	emulator deploy examples use --device, --cpu, --memory (the CLI has --device-profile, and no CPU or memory flags)
emulator-commands.md:14	emulator deploy Options lists --device, --cpu, --memory
SKILL.md:89, emulator-commands.md:48,64	emulator list documents and uses --vm
SKILL.md:154	orka3 regcred delete: the subcommand is remove
image-commands.md:28	orka3 image list --arch amd64: image list has no --arch
cicd-workflows.md:34,45	vm-config create --namespace: VM configs live only in orka-default, and vm-config create has no --namespace

The emulator hits are the expected ones and are fixed in other open PRs. The regcred delete, image list --arch, and vm-config create --namespace hits are new.

Warnings against 3.7.0-alpha: emulator deploy Options leaves out --device-profile, --generate-name, --namespace, --output; emulator list leaves out --namespace; vm deploy and vm-config create leave out --display-dpi, --display-height, --display-width, --legacy-io, and vm-config create also --node.

Against 3.6.4 the extra errors are the emulator commands themselves, which 3.6.4 doesn't have. Also checked: --binary-name orka skips all 573 orka3 lines and headings, and a fixture file confirmed that a "Removed in Orka" section is skipped, unknown subcommands are reported, and flags after $(...), pipes, and \ continuations are attributed correctly.

Notes

• CLI_VERSION is 3.7.0-alpha, not 3.6.4. latest.json reports 3.6.4 as the current release, but the skill documents the 3.7.0-alpha emulator commands, and #422 uses 3.7.0-alpha too. Against 3.6.4 every emulator heading and example fails, so the check would stay red. Say so if you want 3.6.4 instead; it is a one-line change.
• This PR fixes no skill content, so the check fails on this PR until the findings above are fixed in their own PRs.
• Options lists are compared only in orka3-cli/references/commands/, and only for commands that have an Options list, so a command with no list isn't warned about.
• Short flags in examples (-o, -n) are checked too. Combined short flags like -abc are skipped.
• I ran the macOS build locally because Docker wasn't running. The workflow's first run on this PR used the Linux build and got the same result (15 errors, 14 warnings), so the check fails here as expected.

🤖 Generated with Claude Code