fix(cli): clarify login method selection

[TheodoreSpeaks]

Summary

• Replace --browserless with --method oauth|api-key. Explicit OAuth fails if unavailable; --no-browser only controls opening the link.
• Remove login --scope and always request a platform API key from pairing.
• Update help, errors, authentication docs, and regression tests.

Type of Change

• Bug fix

Testing

• CLI suite: 940 passed, 1 skipped.
• CLI type-check and repo lint passed.
• All 46 repo audits and docs-manifest check passed, including strict API validation and CLI docs checks.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 8, 2026 1:55am UTC

[greptile-apps]

Greptile Summary

This PR clarifies CLI login method selection and credential behavior.

• Replaces --browserless and --scope with explicit --method oauth|api-key selection.
• Keeps automatic OAuth preference while using API-key pairing for remote sessions or unavailable OAuth.
• Ensures pairing always requests and accepts only platform API keys.
• Updates CLI tests, errors, help text, and authentication documentation.
• Corrects existing-key instructions to use SIM_API_KEY and documents legacy-server compatibility requirements.

Confidence Score: 5/5

The PR appears safe to merge; the follow-up changes correct the documentation issues without introducing a new actionable defect.

No outstanding blocking failure remains. TheodoreSpeaks accepted the fail-closed handling of incompatible legacy pairing responses because Copilot-scoped keys cannot authenticate the platform CLI, and the documentation now clearly states the compatibility requirement and potential need to upgrade. The unsupported --api-key documentation was fully corrected to use SIM_API_KEY.

Important Files Changed

Filename	Overview
packages/sim-cli/src/commands/auth.ts	Implements explicit login-method selection, validates incompatible options, and restricts pairing to platform API keys.
packages/sim-cli/src/auth/device-flow.ts	Simplifies approval URL generation so pairing always requests platform scope.
packages/sim-cli/src/commands/auth.test.ts	Adds regression coverage for explicit methods, unavailable OAuth, invalid options, remote detection, and incompatible returned keys.
apps/docs/content/docs/cli/authentication.mdx	Documents method selection, callback behavior, platform-pairing requirements, and supported existing-key configuration.
packages/sim-cli/README.md	Aligns package-level login guidance with the implemented method and credential behavior.

_{Reviews (2): Last reviewed commit: "fix(cli): correct API-key authentication..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@TheodoreSpeaks I have started the AI code review. It will take a few minutes to complete.