nexos-connect 0.5.0 → 0.6.0

package/README.md

@@ -9,7 +9,7 @@ One key, one model, one command.
 ![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
 ![License](https://img.shields.io/badge/license-MIT-blue)
 
-[Quick start](#quick-start) · [Usage](#usage) · [Supported agents](#supported-agents) · [Undo](#undo) · [Development](#development)
+[Quick start](#quick-start) · [Usage](#usage) · [Supported agents](#supported-agents) · [Undo](#undo) · [Status](#status) · [Development](#development)
 
 </div>
 
@@ -52,13 +52,20 @@ diff for every file:
     }
 ```
 
+If Codex reports `Missing environment variable: NEXOS_API_KEY`, try this model override, replacing `<selected-model>` with the model chosen during setup. This is a reported workaround, not a required launch command or a guaranteed fix:
+
+```bash
+codex -c 'model="<selected-model>"'
+```
+
 > [!IMPORTANT]
-> OpenAI Codex and GitHub Copilot CLI read the key from the environment. Load it once setup is done,
-> and add the same line to your shell profile to keep it:
+> OpenAI Codex and GitHub Copilot CLI read the key from the environment. On Windows, setup also
+> sets it in your user environment, so a **new terminal** just works — no dot-sourcing. On macOS and
+> Linux, load it once and add the line to your shell profile to keep it:
 >
 > ```bash
 > source ~/.nexos/env              # macOS, Linux
-> . "$HOME\.nexos\env.ps1"         # Windows PowerShell
+> . "$HOME\.nexos\env.ps1"         # Windows PowerShell, for the current session only
 > ```
 
 ## Usage
@@ -66,8 +73,9 @@ diff for every file:
 | Command                        | What it does                                                                                              |
 | ------------------------------ | --------------------------------------------------------------------------------------------------------- |
 | `npx nexos-connect`            | Set up your agents, interactively                                                                         |
-| `npx nexos-connect <agent>`    | Start one agent on the gateway **without changing its config** — `claude`, `codex`, `opencode`, `copilot` |
+| `npx nexos-connect <agent>`    | Start one agent on the gateway **without changing its config** — `claude`, `codex`, `opencode`, `copilot`, `pi`, `crush`, `qwen` |
 | `npx nexos-connect restore`    | Put back what nexos-connect changed                                                                       |
+| `npx nexos-connect status`     | Report what is configured, and whether it still matches — read-only                                       |
 | `npx nexos-connect forget-key` | Delete the key saved in your system keychain                                                              |
 
 ```bash
@@ -80,9 +88,15 @@ npx nexos-connect --scope project
 # No questions asked — for scripts
 npx nexos-connect --harnesses claude-code,codex --key "$NEXOS_API_KEY" --yes
 
+# A fresh machine — pick the agents; a missing one is installed, then configured
+npx nexos-connect
+
 # Try Claude Code on the gateway, leaving its config alone
 npx nexos-connect claude
 
+# Start an agent you have not installed yet — the CLI installs it first
+npx nexos-connect claude --install
+
 # Anything after -- goes to the agent
 npx nexos-connect codex -- exec "fix the tests"
 ```
@@ -90,7 +104,9 @@ npx nexos-connect codex -- exec "fix the tests"
 The default model is the nexos.ai router, which picks a model per request. Before the picker opens,
 nexos-connect checks that your key can use it, and offers the router only when that check passes. A
 check that fails, or one you skip with `--no-verify`, leaves it out. After a failed check you choose
-from the models your key can reach; with `--no-verify` you type a model id. A `--yes` run with no
+from the models your key can reach; with `--no-verify` you type a model id. The picker lists every
+conversational model the Gateway can serve, including ones it reaches through translation, and a
+live probe confirms the model works for the agents you picked. A `--yes` run with no
 `--model` exits `2` only when the gateway rejected the router; anything less certain warns and uses
 it. Naming the router yourself always wins, with a warning only when the gateway rejected it, and
 the router is never saved as an agent's default. Save any other model your key can reach as an
@@ -106,11 +122,14 @@ agent's default for next time.
 | `--save-key`          | Save the key in your system keychain for future runs                                          |
 | `--model <id>`        | Model every agent uses. Falls back to `$NEXOS_MODEL`, then the saved default, then a picker   |
 | `--save-model`        | Save the model as each agent's default                                                        |
+| `--install`           | Install a not-installed agent with `npm install -g`. Setup installs the ones you pick in the list; starting an agent installs the named one first. `--yes` never installs |
 | `--scope <scope>`     | `user` (default — your home directory) or `project` (this directory only)                     |
 | `-y`, `--yes`         | Answer every question with its default and write without asking                              |
 | `--dry-run`           | Show the diffs and write nothing                                                              |
 | `--no-verify`         | Skip the gateway checks — key, model list and router — e.g. when offline. Without a check, the router is not offered |
 | `--backup-dir <path>` | Where originals are copied. Default `~/.nexos/backups/`, or `./.nexos-backup/` for a project  |
+| `--verify`            | With `status`: check the resolved key against the gateway once                                |
+| `--json`              | With `status`: print the report as one JSON object                                            |
 
 Exit codes: `0` done · `1` an agent failed · `2` usage error · `130` cancelled.
 Run `npx nexos-connect --help` for the full reference.
@@ -147,14 +166,31 @@ Every setting nexos-connect wrote goes back to what it was before the first run;
 since stays. Copies of the original files are kept under `~/.nexos/backups/` (or `./.nexos-backup/`
 for a project).
 
+## Status
+
+```bash
+npx nexos-connect status
+```
+
+`status` is read-only and never writes. It reports the key, the env file, the backup folders and the
+saved defaults, then one block per agent, at user and project scope: `configured`, `drifted`,
+`not configured`, `not installed` or `unreadable`. `drifted` means a fresh setup would change the
+file. Add `--verify` to check the resolved key against the gateway, and `--json` for a
+machine-readable report. It exits `1` when an agent has drifted, a config cannot be read, a
+`--harnesses`-named agent is not configured or not installed, a read fails, or `--verify` rejects
+the key.
+
+`status` judges `configured` and `drifted` against the gateway the run talks to: `$NEXOS_BASE_URL`
+when set, else the canonical `https://api.nexos.ai`.
+
 ## Your key
 
 Your key is never printed in full — not in diffs, reports or gateway errors. Save it with `--save-key`
 and later runs offer it from your system keychain (macOS Keychain, Windows Credential Manager, or the
 Secret Service on Linux); `npx nexos-connect forget-key` removes it.
 
-Setup still writes the key in plain text to each agent's config and to `~/.nexos/env`, where the agents
-read it; a saved key does not change that.
+Setup still writes the key in plain text to each agent's config and to `~/.nexos/env` (and, on
+Windows, to your user environment), where the agents read it; a saved key does not change that.
 
 ## Development