@agent-nexus/cli 0.1.6 → 0.1.7

package/README.md

@@ -125,6 +125,80 @@ The CLI resolves the API key in this order (first match wins):
 | 4        | `NEXUS_ENV` env var      | `production` = `https://api.nexusgpt.io`, `dev` = `http://localhost:3001` |
 | 5        | Default                  | `https://api.nexusgpt.io`                                                 |
 
+### Multi-Profile Support
+
+The CLI supports multiple named profiles for managing different organizations or environments.
+
+#### Create profiles
+
+```bash
+# Interactive (opens browser, prompts for key and profile name)
+nexus auth login
+
+# Non-interactive with explicit profile name
+nexus auth login --profile work --api-key nxs_abc123
+nexus auth login --profile personal --api-key nxs_xyz789
+```
+
+#### Switch between profiles
+
+```bash
+nexus auth switch work
+nexus auth switch personal
+```
+
+#### List all profiles
+
+```bash
+nexus auth list
+#  PROFILE    ORGANIZATION   BASE URL
+# ▸ work      Acme Corp      https://api.nexusgpt.io
+#   personal  My Startup     https://api.nexusgpt.io
+```
+
+#### Pin a directory to a profile
+
+Create a `.nexusrc` file in your project directory so the CLI automatically uses the right profile:
+
+```bash
+cd ~/projects/acme
+nexus auth pin work
+# Creates .nexusrc with { "profile": "work" }
+
+cd ~/projects/startup
+nexus auth pin personal
+```
+
+#### Check which profile is active
+
+```bash
+nexus auth status
+# Using profile "work" (Acme Corp) — .nexusrc at /Users/you/projects/acme/.nexusrc
+```
+
+#### Profile Resolution Order
+
+When determining which profile to use, the CLI checks (first match wins):
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 | `--api-key` flag or `NEXUS_API_KEY` env | Bypasses profiles entirely |
+| 2 | `--profile` flag | `nexus agent list --profile work` |
+| 3 | `NEXUS_PROFILE` env var | `export NEXUS_PROFILE=work` |
+| 4 | `.nexusrc` file | Walks up directory tree to find `.nexusrc` |
+| 5 | Active profile | Set by `nexus auth switch` |
+| 6 | `"default"` profile | Fallback |
+
+#### Remove profiles
+
+```bash
+nexus auth logout           # removes active profile
+nexus auth logout work      # removes specific profile
+nexus auth logout --all     # removes everything
+
+nexus auth unpin            # removes .nexusrc from current directory
+```
+
 ---
 
 ## Quick Start
@@ -183,11 +257,13 @@ These flags are available on every command:
 
 | Flag               | Description                                       |
 | ------------------ | ------------------------------------------------- |
-| `--json`           | Output results as JSON (for scripting and piping) |
-| `--api-key <key>`  | Override the API key for this invocation          |
-| `--base-url <url>` | Override the API base URL                         |
-| `-v, --version`    | Print the CLI version and exit                    |
-| `--help`           | Show help for any command or subcommand           |
+| `--json`             | Output results as JSON (for scripting and piping) |
+| `--api-key <key>`    | Override the API key for this invocation          |
+| `--base-url <url>`   | Override the API base URL                         |
+| `--profile <name>`   | Use a specific named profile                      |
+| `--no-auto-update`   | Disable automatic CLI updates for this invocation |
+| `-v, --version`      | Print the CLI version and exit                    |
+| `--help`             | Show help for any command or subcommand           |
 
 ### Environment Variables
 
@@ -196,6 +272,7 @@ These flags are available on every command:
 | `NEXUS_API_KEY`  | API key (used when `--api-key` flag and config file are absent) |
 | `NEXUS_BASE_URL` | API base URL override                                           |
 | `NEXUS_ENV`      | Environment name: `production` (default) or `dev`               |
+| `NEXUS_PROFILE`  | Profile name override (same as `--profile` flag)                |
 | `NO_COLOR`       | Disable all color output ([no-color.org](https://no-color.org)) |
 
 ---
@@ -337,7 +414,7 @@ All commands follow the pattern: `nexus <group> <action> [arguments] [options]`
 
 | Command                                                    | Subcommands                                                 | Description               |
 | ---------------------------------------------------------- | ----------------------------------------------------------- | ------------------------- |
-| [`auth`](docs/command-reference.md#nexus-auth)             | `login` `logout` `whoami`                                   | Authentication            |
+| [`auth`](docs/command-reference.md#nexus-auth)             | `login` `logout` `switch` `list` `pin` `unpin` `status` `whoami` | Authentication            |
 | [`agent`](docs/command-reference.md#nexus-agent)           | `list` `get` `create` `update` `delete` `duplicate`         | AI agent management       |
 | [`agent-tool`](docs/command-reference.md#nexus-agent-tool) | `list` `get` `create` `update` `delete`                     | Agent tool configurations |
 | [`version`](docs/command-reference.md#nexus-version)       | `list` `get` `create` `update` `delete` `restore` `publish` | Prompt version management |
@@ -399,8 +476,9 @@ All commands follow the pattern: `nexus <group> <action> [arguments] [options]`
 
 | Command                                              | Subcommands   | Description                    |
 | ---------------------------------------------------- | ------------- | ------------------------------ |
-| [`api`](docs/command-reference.md#nexus-api)         | (passthrough) | Call any API endpoint directly |
-| [`upgrade`](docs/command-reference.md#nexus-upgrade) | (self-update) | Upgrade the CLI to latest      |
+| [`api`](docs/command-reference.md#nexus-api)         | (passthrough)  | Call any API endpoint directly |
+| [`docs`](docs/command-reference.md#nexus-docs)       | (topic browser) | View built-in documentation    |
+| [`upgrade`](docs/command-reference.md#nexus-upgrade) | (self-update)  | Upgrade the CLI to latest      |
 
 > **Full reference:** See [docs/command-reference.md](docs/command-reference.md) for complete documentation of every command, option, and example.
 
@@ -626,22 +704,42 @@ sudo npm install -g @agent-nexus/cli@latest
 
 ## Configuration Files
 
-| File                              | Purpose                                              | Permissions |
-| --------------------------------- | ---------------------------------------------------- | ----------- |
-| `~/.nexus-mcp/config.json`        | API key and base URL (written by `nexus auth login`) | `0600`      |
-| `~/.nexus-mcp/version-check.json` | Update check cache (auto-managed, checked once/day)  | `0600`      |
+| File | Purpose | Permissions |
+|------|---------|-------------|
+| `~/.nexus-mcp/config.json` | Profiles with API keys and base URLs | `0600` |
+| `~/.nexus-mcp/version-check.json` | Update check cache (auto-managed, checked once/day) | `0600` |
+| `.nexusrc` | Directory-level profile pinning (created by `nexus auth pin`) | — |
 
-The `~/.nexus-mcp/` directory is created with `0700` permissions. This path is shared with the [`@nexus/mcp-server`](../mcp-server/) package, so logging in via the CLI also authenticates the MCP server.
+The `~/.nexus-mcp/` directory is created with `0700` permissions. This path is shared with the [`@nexus/mcp-server`](../mcp-server/) package.
 
-### Config File Format
+### Config File Format (V2)
 
 ```json
 {
-  "apiKey": "nxs_your_api_key_here",
-  "baseUrl": "https://api.nexusgpt.io"
+  "activeProfile": "work",
+  "profiles": {
+    "work": {
+      "apiKey": "nxs_...",
+      "baseUrl": "https://api.nexusgpt.io",
+      "orgName": "Acme Corp",
+      "orgId": "org_..."
+    },
+    "personal": {
+      "apiKey": "nxs_...",
+      "orgName": "My Startup"
+    }
+  }
 }
 ```
 
+### .nexusrc Format
+
+```json
+{ "profile": "work" }
+```
+
+Place in your project root. The CLI walks up the directory tree to find it. Consider adding `.nexusrc` to `.gitignore`.
+
 ---
 
 ## Related Resources