refactor(cli): co-locate command registration in each command folder

[rafa-thayto]

What

Splits the command-registration wiring out of the monolithic packages/cli-core/src/cli-program.ts (1109 lines) into per-command registerX(program) functions co-located in each command's folder. createProgram() is now a short, ordered list of registerX(program) calls.

packages/cli-core/src/cli-program.ts | 860 +--------------------

This makes each command's surface (name, flags, examples, action) owned by its own folder — you add or change a command by editing commands/<name>/index.ts, not by editing one giant file. It follows the pattern already established by registerExtras(program).

How it works

• Each command folder exposes export function registerX(program: Command): void holding its own .command()/.option()/.setExamples()/.action() chain (mirrors the existing registerExtras precedent).
• New commands/toggles/ owns the shared enable/disable parents, wiring the orgs + billing handlers under both (neither feature folder cleanly owns those parents).
• Shared option parsers (parseIntegerOption, collectOptionValues) extracted to lib/option-parsers.ts; the users-only USER_LIST_ORDER_BY_CHOICES moved into the users folder.
• Removed the now-dead apps/users aggregate exports that only existed to feed cli-program.ts.

Behavior

No user-facing change. Registration order is preserved exactly, so clerk --help and every subcommand's help is unchanged. This was verified by capturing the full --help tree (39 command nodes) from main before the change and diffing it against the result after — byte-identical.

Test plan

• bun run format — clean
• bun run typecheck — clean
• bun run lint — 0 warnings, 0 errors
• bun run build:compile — compiles (336 modules)
• bun run test — no new failures introduced (pre-existing local-env failures unchanged vs main; full verdict from CI)
• --help tree byte-identical across all 39 nodes (init, auth, link, unlink, whoami, open, apps, users, env, config, enable/disable, api, doctor, switch-env, completion, skill, update, bird)
• Multi-agent review (migration-fidelity + security/performance/TypeScript/code-quality) — cleared

Empty changeset included (internal refactor, no user-facing impact).

[changeset-bot]

🦋 Changeset detected

Latest commit: 59dee03

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Review limit reached

@rafa-thayto, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 51 minutes and 31 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 29ffb15a-2555-476d-ad52-ee894fa9821f

📥 Commits

Reviewing files that changed from the base of the PR and between 999e72a and 569e165.

📒 Files selected for processing (22)

• .changeset/fancy-frogs-open.md
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/api/index.ts
• packages/cli-core/src/commands/apps/index.ts
• packages/cli-core/src/commands/auth/index.ts
• packages/cli-core/src/commands/completion/index.ts
• packages/cli-core/src/commands/config/index.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/doctor/index.ts
• packages/cli-core/src/commands/env/index.ts
• packages/cli-core/src/commands/init/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/open/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/toggles/README.md
• packages/cli-core/src/commands/toggles/index.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/commands/update/index.ts
• packages/cli-core/src/commands/users/index.ts
• packages/cli-core/src/commands/whoami/index.ts
• packages/cli-core/src/lib/option-parsers.test.ts
• packages/cli-core/src/lib/option-parsers.ts

📝 Walkthrough

Walkthrough

This PR refactors the Clerk CLI from a monolithic command wiring approach in cli-program.ts to a modular architecture where each command group is registered through dedicated register* functions. The main program file delegates command registration to individual modules (registerInit, registerAuth, registerLink, etc.), eliminating ~800 lines of inline command definitions. Supporting utilities for option parsing (collectOptionValues, parseIntegerOption) are introduced, and the users command export is made internal. All CLI behavior and public APIs remain unchanged; this is a structural reorganization only.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• clerk/cli#287: Modifies createProgram() output handling and logging configuration in tandem with command registration changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main refactoring: moving CLI command registration from a monolithic file into per-command functions colocated in each command folder.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the refactoring rationale, implementation approach, behavioral impact, and test verification.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[rafa-thayto]

!snapshot

[coderabbitai]

Actionable comments posted: 0