From 395b2ddc5b43cd219859bf8351565c5f27010e85 Mon Sep 17 00:00:00 2001
From: Kishore Kumar <nkishore@megam.io>
Date: Sat, 24 Oct 2026 15:31:55 +0530
Subject: [PATCH 1/2] docs: explain approved local terminal sign-in

---
 changelog.mdx                    | 10 +++++
 cli/agentsfleet.mdx              | 65 ++++++++++++++++++++++++++++++--
 cli/configuration.mdx            |  9 +++--
 tutorials/github-pr-reviewer.mdx | 16 +++++---
 4 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/changelog.mdx b/changelog.mdx
index 213ef82..8dd8341 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -7,6 +7,16 @@ description: "Product changes and upgrade notes."
   agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner.
 </Tip>
 
+<Update label="Oct 24, 2026" tags={["CLI"]}>
+  ## Authorize terminal sign-in without copying a code
+
+  `agentsfleet login` uses your browser on the same computer. Compare the check codes before choosing **Authorize**, and the terminal completes sign-in after approval.
+
+  - **Cancellation** — press **Esc** while waiting. Once **Finalizing sign-in…** appears, keep the terminal open until it reports the result.
+  - **Another device** — use `agentsfleet login --no-open` for manual six-digit code entry, including remote terminals.
+  - **Browser launch** — if the browser does not open, use the printed link on the same computer.
+</Update>
+
 <Update label="Oct 24, 2026" tags={["Bug fixes", "CLI"]}>
   ## Clearer page loading and terminal sign-in
 
diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx
index 3c99034..9e476f4 100644
--- a/cli/agentsfleet.mdx
+++ b/cli/agentsfleet.mdx
@@ -64,16 +64,75 @@ Write these after `login`. Only `agentsfleet login` reads them.
 
 | Option | Effect | Default | Unit or range |
 |---|---|---|---|
-| `--no-open` | Prints the login URL instead of opening a browser. | `false` | Boolean |
+| `--no-open` | Uses manual code entry and prints a URL you can open on another device. | `false` | Boolean |
 | `--no-input` | Returns an error instead of asking a question. | `false` | Boolean |
 | `--force` | Signs in again even when this computer already holds a credential. | `false` | Boolean |
-| `--token-name <LABEL>` | Labels this sign-in on the approval page and in `agentsfleet whoami`. | The platform family name | Text |
+| `--token-name <LABEL>` | Sets a label on this sign-in request. | The platform family name | 1 to 64 characters from space through tilde |
+
+#### Browser on this computer
+
+1. Start sign-in from an interactive terminal on the same computer as your browser.
+
+   ```bash
+   agentsfleet login
+   ```
+
+   ```text
+   Connect your terminal
+   Open this link on this computer:
+   login_url: <varies>
+   Check code: <varies>
+   Waiting for authorization… (Esc to cancel)
+   browser: opened
+   <varies>
+   Finalizing sign-in…
+   ✓ signed in as <varies> — <varies>
+   ```
+
+2. Compare the check code in your browser with the code in your terminal.
+3. Choose **Authorize** only if you started the sign-in and both codes match.
+
+After approval, the client saves this computer's credential and checks your identity. The terminal then shows your name and account.
+Choose **Deny** if you did not start the sign-in or the codes differ.
+
+Press **Esc** or **Ctrl+C** while waiting to cancel. The waiting request expires after five minutes.
+
+Once **Finalizing sign-in…** appears, cancellation is disabled until sign-in finishes. Keep the terminal open until it reports the result.
+
+If the browser does not open, open the printed `login_url` on this computer.
+If the browser cannot reach your terminal, cancel while waiting and restart with `--no-open`.
+Start a new sign-in if the request expires.
+
+#### Browser on another device
+
+Use manual code entry for a remote terminal, such as a Secure Shell (SSH) session, or a browser on another device.
+
+1. Start manual sign-in in your interactive terminal.
+
+   ```bash
+   agentsfleet login --no-open
+   ```
+
+   ```text
+   Login session
+   session_id: <varies>
+   login_url: <varies>
+   browser: not opened (open URL manually)
+   Enter the 6-digit verification code shown in your browser: <varies>
+   ```
+
+2. Open the printed `login_url` in your browser.
+3. Choose **Authorize** only if you started this sign-in.
+4. Enter the browser's six-digit verification code in the terminal that started sign-in.
+
+The terminal reports **signed in as** with your name and account after sign-in succeeds.
+Manual sign-in requires terminal input, so omit `--no-input`.
 
 ### Account and diagnosis
 
 | Command | Effect |
 |---|---|
-| `agentsfleet login` | Opens browser sign-in. Choose **Authorize**, then enter the displayed code in your terminal to save this computer's credential. |
+| `agentsfleet login` | Opens same-computer browser authorization and saves a credential after approval. |
 | `agentsfleet logout` | Revokes this computer's credential and any unfinished sign-in, then clears local credentials. Browser sessions stay signed in. |
 | `agentsfleet whoami` | Shows who this terminal is signed in as, the credential's source (`environment` or `file`), and the server it talks to. |
 | `agentsfleet doctor` | Checks client settings, authentication, and API access. |
diff --git a/cli/configuration.mdx b/cli/configuration.mdx
index 3eb2aae..d9ed754 100644
--- a/cli/configuration.mdx
+++ b/cli/configuration.mdx
@@ -14,7 +14,10 @@ The client reads command options, environment variables, saved login data, and b
 
 For authentication, `AGENTSFLEET_API_KEY` overrides the saved login credential.
 
-Run `agentsfleet login`, then choose **Authorize** in the browser. Return to the terminal and enter the displayed code to finish signing in. Continue only if you started the sign-in.
+Run `agentsfleet login` with a browser on the same computer. Compare the check code in both places before choosing **Authorize**. The terminal completes sign-in after approval.
+
+For a remote terminal or another device, use `agentsfleet login --no-open` with manual code entry.
+See [terminal sign-in](/cli/agentsfleet#browser-on-this-computer) for cancellation, browser launch failures, and manual steps.
 
 The command accepts no token on the command line and reads no token from piped input.
 
@@ -35,7 +38,7 @@ AGENTSFLEET_API_URL=https://api.agentsfleet.net agentsfleet --version
 | Name | Effect | Default | Valid range |
 |---|---|---|---|
 | `AGENTSFLEET_API_URL` | Sets the API base URL. | `https://api.agentsfleet.net` | URL beginning with `http://` or `https://` |
-| `AGENTSFLEET_DASHBOARD_URL` | Sets the browser login URL. | `https://app.agentsfleet.net` | URL beginning with `http://` or `https://` |
+| `AGENTSFLEET_DASHBOARD_URL` | Sets the dashboard origin for browser sign-in. | `https://app.agentsfleet.net` | `http://` or `https://` origin; no extra path, query, fragment, or credentials |
 | `AGENTSFLEET_API_KEY` | Authenticates every request and overrides saved login data. Nothing is written to disk. | None | Valid tenant API key starting with `agt_t` |
 | `AGENTSFLEET_STATE_DIR` | Stores local credentials, settings, and telemetry consent. | `~/.config/agentsfleet` | Writable directory path |
 | `NO_COLOR` | Disables color when set to a nonempty value. | Unset | Any nonempty text |
@@ -49,7 +52,7 @@ The API URL uses this order: `--api`, `AGENTSFLEET_API_URL`, the server recorded
 
 An invalid URL returns exit code `4`. A missing credential returns exit code `1`.
 
-A network failure returns exit code `2`. The client does not change saved login data after a network failure.
+Most commands report network failures with exit code `2`. Login reports sign-in failures with exit code `1`.
 
 A saved credential that records no server returns exit code `1` with error code `DEPLOYMENT_UNKNOWN`. Nothing is sent. Pass `--api <API_URL>`, set `AGENTSFLEET_API_URL`, or run `agentsfleet login` again.
 
diff --git a/tutorials/github-pr-reviewer.mdx b/tutorials/github-pr-reviewer.mdx
index 31dfcfb..7ed60cd 100644
--- a/tutorials/github-pr-reviewer.mdx
+++ b/tutorials/github-pr-reviewer.mdx
@@ -52,21 +52,27 @@ For a connected GitHub App, follow [Configure a webhook](/fleets/webhooks#a-conn
    <varies>
    ```
 
-3. Sign in through your browser.
+3. Sign in through a browser on the same computer as your terminal.
 
    ```bash
    agentsfleet login
    ```
 
    ```text
-   Login session
-   session_id: <varies>
+   Connect your terminal
+   Open this link on this computer:
    login_url: <varies>
+   Check code: <varies>
+   Waiting for authorization… (Esc to cancel)
    browser: opened
-   login complete
+   <varies>
+   Finalizing sign-in…
+   ✓ signed in as <varies> — <varies>
    ```
 
-   Choose **Authorize** in your browser. Return to your terminal and enter the six-digit code when prompted.
+   Compare the check code in your browser with your terminal. Choose **Authorize** only if you started the sign-in and both codes match.
+
+   For a remote terminal or another device, use `agentsfleet login --no-open` and follow [manual sign-in](/cli/agentsfleet#browser-on-another-device).
 
    Login keeps your previous workspace if it is still available; otherwise it selects the first available workspace.
    Check `agentsfleet workspace show` before saving secrets.

From a1cd28e48a8ebc67fef91443f0ee1694f694c2b2 Mon Sep 17 00:00:00 2001
From: Kishore Kumar <nkishore@megam.io>
Date: Sun, 25 Oct 2026 22:43:49 +0530
Subject: [PATCH 2/2] docs: align login failure exit codes across references

---
 cli/agentsfleet.mdx | 4 +++-
 cli/flags.mdx       | 7 ++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx
index 9e476f4..e33500e 100644
--- a/cli/agentsfleet.mdx
+++ b/cli/agentsfleet.mdx
@@ -3,7 +3,7 @@ title: Command reference
 description: Commands available in the agentsfleet command-line client.
 type: reference
 audience: user
-verified: 2026-10-24
+verified: 2026-10-25
 product_version: 0.65.0
 executable: false
 ---
@@ -450,6 +450,8 @@ Charges for the same fleet event group within each page. Every returned charge c
 | `5` | Local configuration is missing or invalid. |
 | `130` | You interrupted the command. |
 
+Login reports network and API sign-in failures with exit code `1`.
+
 A rejected invocation is answered before any request is sent. The form is always the same: what is wrong, then the command that puts it right. What is wrong may be an absent argument, a value that failed validation, or an unrecognized command.
 
 ```
diff --git a/cli/flags.mdx b/cli/flags.mdx
index 79a66a4..43eb706 100644
--- a/cli/flags.mdx
+++ b/cli/flags.mdx
@@ -3,8 +3,8 @@ title: Global options
 description: Options accepted by the agentsfleet command-line client.
 type: reference
 audience: user
-verified: 2026-10-19
-product_version: 0.62.1
+verified: 2026-10-25
+product_version: 0.65.0
 executable: true
 ---
 
@@ -45,7 +45,8 @@ agentsfleet --version
 
 The client returns exit code `0` after success. Authentication and unexpected failures return `1`.
 
-Network failures return `2`. API failures return `3`.
+Most commands return `2` for network failures and `3` for API failures.
+Login returns `1` for those sign-in failures.
 
 Invalid command input returns `4`. Local configuration failures return `5`.