docs(cli): device login (--device) for sandboxed agents

[tonychang04]

Teaches agents the device-login flow for sandboxes where the browser can't reach the CLI's loopback callback (ChatGPT app, SSH, containers).

Per Tony's direction this documents only login --device (RFC 8628) — the paste-back --no-browser/--callback-url mechanism exists in the CLI but is deliberately not taught to agents.

• references/login.md: Device login section — run login --device --json, relay the pre-filled link + code, user clicks Authorize, CLI polls to completion; rerun resumes the same pending code after a sandbox kills the process.
• SKILL.md: auth guidance points agents at --device when a browser exists but can't reach the CLI.

Retrieval-tested: an agent given only this doc chose the right command, relayed the link properly, handled the killed-process resume, and knew the user never pastes anything back.

Merge after the CLI release that ships --device (InsForge/CLI#199; backend InsForge/insforge-cloud-backend#733 must be deployed first). After merge: bump version in .codex-plugin/plugin.json and re-upload the plugin zip to the OpenAI portal — portal snapshots are frozen.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GcszudKMZBSm5RMP14h7fu

[coderabbitai]

Walkthrough

The CLI documentation now describes login --device for sandboxed environments, including approval, polling, interruption recovery, and JSON usage. The skill guidance incorporates this workflow alongside existing browser-based and API-key authentication instructions.

Changes

Device login documentation

Layer / File(s)	Summary
Document the device authorization flow skills/insforge-cli/references/login.md	Adds the --device option, sandbox workflow, verification link and code handling, pending-login resumption, and a JSON example.
Integrate device login into skill guidance skills/insforge-cli/SKILL.md	Adds device-login guidance for sandboxes where the local OAuth callback is inaccessible while retaining existing login paths.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: fermionic-lyu, jwfing

Poem

I’m a rabbit with a code to share,
A login link hops through the air.
The CLI polls, the sandbox sings,
Device flow grants access wings.
Two docs now guide the way—
Hop, approve, and work today!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: documenting CLI device login for sandboxed agents.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/login-no-browser

---

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

[jwfing]

Summary

Docs-only change (+27/−1) adding a --device (RFC 8628) sandbox login section to references/login.md and pointing SKILL.md auth guidance at it; the documented behavior is technically accurate against the real CLI implementation, but the PR's traceability metadata points at the wrong companion PR.

Requirements context

No /docs/superpowers/ (or docs/specs/) directory exists in insforge-skills — this repo is a skills/reference-docs collection with no spec/plan files. No matching spec/plan found; I assessed against the PR description, the repo's CONTRIBUTING.md doc conventions, and — critically for a docs PR — the actual CLI implementation this documents. I cross-checked every documented fact against the companion CLI PRs (InsForge/CLI#198 and #199) at their current head commits.

Verification result — the documented facts are correct. Every concrete claim in the new section matches the real implementation in InsForge/CLI#199 (feat(login): --device login via RFC 8628 device flow):

• --device flag → src/commands/login.ts .option('--device', …) ✓
• Verification URL https://insforge.dev/auth/device?user_code=BCDF-GHJK → matches verification_uri_complete in auth.device.test.ts ✓
• Printed prompt text ("To sign in, ask the user to open: … and confirm the code …") → matches the process.stderr.write string in auth.ts ✓
• ~/.insforge/pending-device.json → config.ts PENDING_DEVICE_FILE ✓
• "Codes expire after 15 minutes" → expires_in: 900 in the device-authorization fixtures ✓
• Resume-same-code on rerun with same $HOME → getResumableDeviceLogin / auth.device.resume.test.ts ✓

No hallucinated or stale API usage in the doc body. Nicely done.

Findings

Critical

(none)

Suggestion

• Functionality / traceability — wrong companion PR referenced. The description says "Companion to InsForge/CLI#198", but #198 implements the --no-browser / --callback-url paste-back flow (pending-login.json, 10-min TTL) — a different feature. The --device flow this PR documents is implemented in InsForge/CLI#199 (whose body even states it is "independent of #198 (paste-back)"). Please repoint the companion reference to #199, otherwise a releaser could merge these docs when #198 ships and leave the skill describing a --device command the released CLI doesn't have. (PR description)
• Functionality — release gating is broader than the doc implies. references/login.md:34 gates on @insforge/cli ≥ 0.2 only, but #199 is a draft that "depends on" InsForge/insforge-cloud-backend#733 (device grant + endpoints, "merge first") and InsForge/insforge-cloud#590 (dashboard approve page). Until the backend /oauth/v1/device_authorization endpoint is deployed and the approve page exists, --device fails fast (the CLI throws "Device login is not enabled for this OAuth client"). Suggest holding merge until #199 is released, and consider adjusting the ≥ 0.2 placeholder (the author already flags this) to the real version. (skills/insforge-cli/references/login.md:34)

Information

• Stale auto-generated summaries in the PR body. The "Summary by cubic" and Macroscope NOTE block describe the older --no-browser/--callback-url two-step flow ("Replaces the previous paste-back flow…"), contradicting the current --device diff. These are bot-generated and will refresh, but they make the PR confusing to a human reviewer right now.
• Software engineering. Follows CONTRIBUTING.md doc conventions (options table row, fenced examples, section heading style); the references/login.md relative link in SKILL.md:52 resolves. No lingering --no-browser/--callback-url references remain in the skill. No tests apply to a docs-only change in this repo.
• Security. No security-relevant changes: no secrets or PII introduced; the example user_code (BCDF-GHJK) is a placeholder matching the CLI's test fixtures; the doc correctly notes the device_code is a bearer secret persisted at 0600.
• Performance. Not applicable — documentation only.

Verdict

approved (informational — no Critical findings; a human still gives the explicit GitHub approval via the approve flow). The documented behavior is accurate and well-written. The Suggestions (fix the #198→#199 companion reference; gate merge on #199 + its backend/dashboard deps) are worth resolving before this leaves draft, but none block on doc correctness. This PR is currently a draft and correctly marked "don't merge before the CLI release."

[jwfing]

LGTM - approved.

[jwfing]

LGTM - approved.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[greptile-apps]

Greptile Summary

This PR documents the --device login flag for @insforge/cli (≥ 0.2), enabling a two-step OAuth device flow in sandboxed environments where the CLI's local callback server is unreachable from the user's browser. It also bumps the plugin version to 1.3.0.

• references/login.md: Adds a new "Device login (--device)" section explaining the two-step agent pattern — run step 1 with timeout 15 to capture and relay the verification link, then rerun step 2 to complete polling — plus an updated options table and examples block.
• SKILL.md: Adds a new Core Rules bullet for upfront connection setup ordering and extends the Connection Setup paragraph with the device-flow two-step instructions and a network-domain fallback note.

Confidence Score: 5/5

Documentation-only change; no executable code paths are modified.

All three files contain documentation or metadata updates. The two-step device flow is consistently described across SKILL.md and login.md, both commands correctly include --json, the pending-file resume mechanism and 15-minute expiry are clearly explained, and the network-domain fallback note is accurate. No behavioral regressions are possible from this change.

No files require special attention.

Important Files Changed

Filename	Overview
skills/insforge-cli/references/login.md	Adds a well-structured Device login (--device) section covering the two-step agent pattern, with inline examples and expiry/HOME-sharing notes; no logic errors found.
skills/insforge-cli/SKILL.md	Adds a connection-setup-first core rule and extends the Connection Setup paragraph with the device-login two-step instructions; both commands correctly include --json.
.codex-plugin/plugin.json	Version bump from 1.2.0 to 1.3.0; the trailing newline was also inadvertently removed, but this is cosmetic and does not affect JSON parsing.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent as Agent Harness
    participant CLI as CLI (sandbox)
    participant FS as ~/.insforge/
    participant API as api.insforge.dev
    participant User as User Browser (host)

    Agent->>CLI: Step 1 — timeout 15 login --device --json
    CLI->>API: Request device code
    API-->>CLI: device_code, user_code, verification_uri
    CLI-->>Agent: Prints verification link and short code
    CLI->>FS: Write pending-device.json
    Note over CLI,Agent: timeout kills CLI after 15 s (expected)
    Agent->>User: Relay verification link and code to user
    User->>User: Opens browser, approves code on dashboard
    Agent->>CLI: Step 2 — login --device --json (resume)
    CLI->>FS: Read pending-device.json (same code)
    loop Poll until approved or expired (15 min)
        CLI->>API: Check token status
        API-->>CLI: pending or success
    end
    CLI->>FS: Write credentials.json
    CLI-->>Agent: JSON success object

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Agent as Agent Harness
    participant CLI as CLI (sandbox)
    participant FS as ~/.insforge/
    participant API as api.insforge.dev
    participant User as User Browser (host)

    Agent->>CLI: Step 1 — timeout 15 login --device --json
    CLI->>API: Request device code
    API-->>CLI: device_code, user_code, verification_uri
    CLI-->>Agent: Prints verification link and short code
    CLI->>FS: Write pending-device.json
    Note over CLI,Agent: timeout kills CLI after 15 s (expected)
    Agent->>User: Relay verification link and code to user
    User->>User: Opens browser, approves code on dashboard
    Agent->>CLI: Step 2 — login --device --json (resume)
    CLI->>FS: Read pending-device.json (same code)
    loop Poll until approved or expired (15 min)
        CLI->>API: Check token status
        API-->>CLI: pending or success
    end
    CLI->>FS: Write credentials.json
    CLI-->>Agent: JSON success object

Loading

_{Reviews (2): Last reviewed commit: "docs(cli): connection setup comes before..." | Re-trigger Greptile}

[jwfing]

Summary

Documents the new --device (RFC 8628) sandbox login flow in skills/insforge-cli — accurate against the shipped CLI implementation, well-scoped, and safe to merge.

Requirements context

No matching spec/plan found — insforge-skills has no docs/superpowers/ (or docs/) directory, so this was assessed against the PR intent plus the companion CLI/backend/dashboard PRs. I verified every documented claim against the merged implementation:

• CLI InsForge/CLI#199 — feat(login): --device login via RFC 8628 device flow — merged, released as @insforge/cli@0.2.0 (confirmed latest on npm).
• Backend insforge-cloud-backend#733 — device grant + /api/oauth/v1/device_authorization — merged.
• Dashboard insforge-cloud#590 — /auth/device approval page — merged.

Claim-by-claim, the doc matches the code:

• --device flag and RFC 8628 device grant — matches src/lib/auth.ts (requestDeviceAuthorization / pollForDeviceTokens / performDeviceLogin).
• ~/.insforge/pending-device.json resume behavior — matches src/lib/config.ts (PENDING_DEVICE_FILE) and getResumableDeviceLogin in auth.ts; the "resumes the SAME code, completes immediately if already approved" wording is exactly right.
• "Codes expire after 15 minutes" — matches the CLI's documented 15-minute device-code lifetime (auth.ts).
• Verification URL https://insforge.dev/auth/device?user_code=… and --json success object — match.
• "requires @insforge/cli ≥ 0.2" — satisfied; 0.2.0 is published as latest.

Findings

Critical

(none) — the entire dependency stack (CLI #199, backend #733, dashboard #590) is merged and 0.2.0 is live on npm, so the PR's "don't merge before the CLI release" caveat is now resolved.

Suggestion

• Software engineering / traceability — skills/insforge-cli/references/login.md:52: the resume note is correct, but it's the one claim most likely to drift from the CLI (the 15-minute lifetime and pending-device.json name are both CLI-internal). Consider phrasing it as "resumes an in-progress code (server-controlled lifetime, currently ~15 min)" so the doc doesn't need a follow-up edit if the backend tunes the TTL. Non-blocking.

Information

• Functionality / stale PR description — The PR body says "Companion to InsForge/CLI#198" and describes the two-step --no-browser / --callback-url paste-back flow persisting to pending-login.json. That is a different, superseded approach (CLI#198 is still open and was explicitly branched-away-from by #199). The actual diff correctly documents --device from CLI#199. The doc content is right; only the PR description and its linked companion PR are stale. Worth updating the PR body to point at #199 for future traceability — no change needed to the committed docs.
• Security — no security-relevant changes: no new secrets logged, no user input reaching SQL/shell, no auth checks weakened. The --user-api-key "$INSFORGE_USER_API_KEY" example is pre-existing and unchanged.
• Performance — not applicable (documentation-only change).
• skills/insforge-cli/SKILL.md:52 and the references/login.md sections are internally consistent — the SKILL.md one-liner correctly points agents at the two-step relay ("relay the printed link + code … CLI completes by itself") and defers detail to references/login.md. No leftover references to the old paste-back flow anywhere in the diff.

Verdict

approved (informational — a human still gives the explicit GitHub approval via the approve flow). Zero Critical findings; the documentation is accurate against the shipped 0.2.0 CLI and the full backend/dashboard stack is deployed. The one Suggestion and the stale-body note are optional cleanups.

[jwfing]

LGTM - approved.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/insforge-cli/references/login.md`:
- Around line 42-48: Add the `text` language tag to the fenced output block in
the sign-in instructions, preserving the existing example content and
formatting.
- Line 34: Update the OAuth guidance in the sandboxed-environment section to
state that the default callback flow waits until its callback timeout, rather
than claiming it hangs forever. Preserve the recommendation to use the device
flow and its existing behavior details.

🪄 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: 5b9ca007-9191-40d3-8dc5-eb716cb1b596

📥 Commits

Reviewing files that changed from the base of the PR and between 3847fe7 and dd9a058.

📒 Files selected for processing (2)

• skills/insforge-cli/SKILL.md
• skills/insforge-cli/references/login.md

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[jwfing]

Review — docs(cli): device login (--device) for sandboxed agents

Summary: Docs-only change adding a --device (RFC 8628 device-login) section to references/login.md and a two-step sandbox-auth pointer in SKILL.md; the documented behavior is accurate and well-crafted, verified against the merged CLI implementation.

Requirements context

No /docs/superpowers/ (or docs/specs/) directory exists in this repo — it is a skills/docs repo with no spec/plan or test suite, so this is assessed against the PR description, SKILL.md, and the actual companion CLI implementation. The PR body links InsForge/CLI#198, but that PR implements a different flow (--no-browser / --callback-url, gcloud-style paste-back). The behavior these docs describe (--device, RFC 8628, short-code + polling, "nothing to paste") is implemented by InsForge/CLI#199, which merged to main on 2026-07-16 (merge commit de015a4). I verified every documented claim against that merged code (src/commands/login.ts, src/lib/auth.ts, src/lib/config.ts).

Findings

Critical

(none) — all documented commands, flags, file paths, and behavior match the merged CLI code.

Suggestion

• Functionality — companion-PR link is stale/incorrect (PR description). The body says "Companion to InsForge/CLI#198", but #198 is the paste-back --no-browser/--callback-url flow, not the --device device-code flow these docs describe. The docs actually match CLI#199 (merged). Please re-point the description/changelog to #199 so the linkage and any release notes are correct. (Doc content is unaffected — only the reference.)
• Functionality — merge gate is already satisfied; consider updating the note (references/login.md:34, PR body). The doc requires @insforge/cli ≥ 0.2 and the body says "don't merge before the CLI release that ships the flags." v0.2.0 is tagged and package.json on main is 0.2.0, and #199 is merged — so the release gate is cleared. The "≥ 0.2" line is accurate; the blocking caveat in the description is now moot.

Information

• Functionality — resume is conditional, doc slightly simplifies (references/login.md:36,60). The doc says the rerun "resumes the SAME pending code." In the implementation (auth.ts getResumableDeviceLogin) resume only happens when the pending code has > 60s of its lifetime left and the platform/client match; a denied/expired code is cleared and the rerun mints a fresh code. The 15-minute lifetime makes the happy path dominant, so this is a fair simplification — just noting the edge case.
• Software engineering — illustrative output omits a line (references/login.md:45-51). The real non-interactive message also includes "If they already approved, this completes immediately." before "Waiting for approval…". The example is prefixed "e.g." so this is fine; optionally mirror the exact wording.
• Software engineering — plugin.json lost its trailing newline (.codex-plugin/plugin.json). The version bump (1.2.0 → 1.3.0) also dropped the final newline (\ No newline at end of file in the diff). Harmless, but re-adding the newline keeps the file POSIX-clean and avoids a noisy diff next time.

Security — no concerns

Verified that relaying step-1 output is safe: the verification link + user code are written to stderr (hence the doc's correct 2>&1 capture), and the only stdout in --json mode is { success: true, user } on completion — no access/refresh tokens or API keys are printed, so relaying the captured output to the user leaks no secrets. The --device flow also avoids the paste-back of a callback URL entirely. SKILL.md continues to correctly warn that InsForge keys are full-access admin keys.

Performance — not applicable

Documentation-only change.

Verdict

approved (informational — no Critical findings). Posted as a COMMENT; explicit GitHub approval remains a separate human action. Suggest addressing the companion-link fix before merge for changelog accuracy, but it is non-blocking.

[jwfing]

LGTM - approved.

[jwfing]

LGTM - approved.