feat: extend next-step suggestions to more commands

[rafa-thayto]

Summary

• Adds contextual next-step output to eight commands: auth logout, switch-env, unlink, whoami, completion, skill install, config patch, and config put.
• Centralizes the new strings in the NEXT_STEPS registry (lib/next-steps.ts); per-shell completion install hints stay local to commands/completion/index.ts since they aren't reusable vocabulary.
• All suggestions are gated on isHuman() via the existing printNextSteps helper, so agent mode and piped output stay clean.

What users see now

After commands like clerk unlink or clerk skill install, the success line is followed by 1–3 cyan arrows pointing at the natural next workflow step (e.g. clerk apps list, clerk config pull, clerk doctor). whoami branches between linked / unlinked profiles for relevance. completion emits stderr-only install hints tailored per shell (bash/zsh/fish/powershell).

Side-effect: whoami resilience fix

The previous try/catch wrapped both fetchUserInfo and log.data(userInfo.email) and attributed any throw to session_expired. Tightened the try to the network call only — incidental but worth noting.

Test plan

• bun run typecheck — pass
• bun run lint — 0 warnings, 0 errors
• bun run test — 82 files pass, 0 fail (179 total tests including the touched commands)
• bun run format — clean
• Manually verified the suggestion text for each command path against the existing NEXT_STEPS style ("Run clerk X to Y")
• CI green

[changeset-bot]

🦋 Changeset detected

Latest commit: 36237e7

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

This PR includes changesets to release 1 package

Name	Type
clerk	Patch

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]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds contextual "next steps" guidance and a changeset for the clerk package. Extends the exported NEXT_STEPS map with entries: SWITCH_ENV, SWITCH_ENV_NO_TOKEN, UNLINK, SKILL_INSTALL, CONFIG_PUSH, LOGOUT, WHOAMI, and WHOAMI_LINKED. Multiple CLI commands now call printNextSteps(...) with the appropriate NEXT_STEPS entry after successful execution: auth logout, completion (shell-specific install hints), config push (non-dry-run), skill install, switch-env (token/no-token paths), unlink, and whoami (uses best-effort local profile resolution). One test was updated to assert the login hint on stderr instead of stdout.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% 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 'feat: extend next-step suggestions to more commands' clearly and concisely describes the main change: extending contextual next-step output to multiple CLI commands.
Description check	✅ Passed	The description is well-structured and directly related to the changeset, detailing what users will see, the implementation approach, and test results.
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.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/cli-core/src/commands/whoami/index.ts`:
- Around line 23-24: Wrap the call to resolveProfile(process.cwd()) in a
try/catch so profile resolution is best-effort: call resolveProfile inside a
try, set a local profile variable only on success, and on any thrown error set
profile to undefined/false (or ignore the error) before calling
printNextSteps(profile ? NEXT_STEPS.WHOAMI_LINKED : NEXT_STEPS.WHOAMI); this
ensures resolveProfile failures don’t make the whoami command fail after account
info was already displayed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 03502c8c-d124-477f-a57c-10ca4fe38c31

📥 Commits

Reviewing files that changed from the base of the PR and between b0c0f0b and 8e13086.

📒 Files selected for processing (10)

• .changeset/more-next-steps.md
• packages/cli-core/src/commands/auth/logout.ts
• packages/cli-core/src/commands/completion/index.ts
• packages/cli-core/src/commands/config/push.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/commands/whoami/index.ts
• packages/cli-core/src/lib/next-steps.ts

[dmoerner]

Approving, I dropped a few more comments on specific wordings on Slack, I'll copy them here:

• CONFIG_PUSH, clerk doctor: I think "integration" is too vague here, like if someone does a push to set up an oauth provider, that might be what they connect to "integration" in context.
• CONFIG_UNLINK: Let's put clerk link first in the array
• SKILL_INSTALL, clerk config pull: I think the message here is kind of misleading, since it's not like doing that will pull the live config into an agent's context. I also wonder if we should make clear that manual clerk init is an alternative if you don't have an agent do it for you. I wonder if we need anything other than telling them to start Claude or whatever. (Or Codex?)
• dry run: We could have the push as the next step.