openhome-cli 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 Command-line tool for managing OpenHome voice AI abilities. Create and deploy abilities without leaving your terminal.
 
-**Status:** v0.1.0 (MVP)
+**Version:** v0.1.2
 **Node:** 18+
 **Platform:** macOS (primary), Linux/Windows (config-file fallback for keychain)
 
@@ -11,14 +11,11 @@ Command-line tool for managing OpenHome voice AI abilities. Create and deploy ab
 ## Install
 
 ```bash
-# Clone and link globally
-git clone https://github.com/Bradymck/openhome-cli.git
-cd openhome-cli
-npm install
-npm run build
-npm link
+# Use directly without installing
+npx openhome-cli
 
-# Now available everywhere
+# Or install globally
+npm install -g openhome-cli
 openhome
 ```
 
@@ -49,21 +46,6 @@ Or just run `openhome` with no arguments for the interactive menu.
 
 Opens an interactive menu. Use arrow keys to navigate, Enter to select. The menu loops after each command — pick another or choose Exit.
 
-```
-┌  OpenHome CLI v0.1.0
-│
-◆  What would you like to do?
-│  ● Log Out
-│  ○ Create Ability
-│  ○ Deploy
-│  ○ Chat
-│  ○ My Abilities
-│  ○ My Agents
-│  ○ Status
-│  ○ Exit
-└
-```
-
 If you are not logged in, the CLI prompts for login before showing the menu.
 
 All commands below also work directly from the terminal.
@@ -84,6 +66,20 @@ openhome login
 
 ---
 
+### `openhome set-jwt [token]`
+
+Save a session token to unlock management commands (`list`, `delete`, `toggle`, `assign`).
+
+```bash
+openhome set-jwt eyJ...
+```
+
+These management commands use OpenHome's web session API, which requires a JWT rather than the SDK API key. To get your token: open [app.openhome.com](https://app.openhome.com), open DevTools then Application then Local Storage then `token`, copy the value, and run `openhome set-jwt <token>`.
+
+The token is saved to `~/.openhome/config.json`. You only need to do this once (until your session expires).
+
+---
+
 ### `openhome init [name]`
 
 Scaffold a new ability with all required files.
@@ -111,39 +107,7 @@ openhome init my-weather-bot
 | `__init__.py` | Required by OpenHome (empty) |
 | `README.md` | Description of your ability |
 
-The generated code auto-validates after creation.
-
----
-
-### `openhome logout`
-
-Clear stored credentials and log out.
-
-```bash
-openhome logout
-```
-
-Removes the API key from macOS Keychain and clears the default agent from config. In the interactive menu, selecting Log Out immediately prompts you to log in again.
-
----
-
-### `openhome chat [agent]`
-
-Chat with an agent via WebSocket. Send text messages and trigger abilities with keywords.
-
-```bash
-# Pick an agent interactively
-openhome chat
-
-# Chat with a specific agent
-openhome chat pers_abc123
-```
-
-Once connected, type messages and press Enter. The agent responds in real-time. Send trigger words (e.g. "play aquaprime") to activate abilities remotely.
-
-Commands inside chat: `/quit`, `/exit`, or `/q` to disconnect. Ctrl+C also works.
-
-> **Note:** Audio responses from the agent are not playable in the terminal. Text responses display normally.
+The generated code auto-validates after creation. You're prompted to deploy immediately.
 
 ---
 
@@ -180,7 +144,7 @@ openhome deploy ./my-ability --personality pers_alice
 3. Asks for confirmation
 4. Uploads to OpenHome
 
-> **Note:** The upload endpoint is not yet live on the server. When it returns "Not Implemented", the CLI saves your zip to `~/.openhome/last-deploy.zip` for manual upload at [app.openhome.com](https://app.openhome.com).
+> **Note:** There is no update/overwrite endpoint yet. Re-deploying with the same name will fail with a naming conflict. Delete the old version first with `openhome delete`.
 
 ---
 
@@ -199,7 +163,64 @@ Shows a table with name, version, status, and last update date.
 
 Status colors: green = active, yellow = processing, red = failed, gray = disabled.
 
-> **Note:** This endpoint is not yet live. Use `--mock` to preview the output format.
+> **Requires session token.** Run `openhome set-jwt <token>` first. See [set-jwt](#openhome-set-jwt-token) above.
+
+---
+
+### `openhome delete [ability]`
+
+Delete a deployed ability.
+
+```bash
+# Pick from a list interactively
+openhome delete
+
+# Delete by name directly
+openhome delete my-weather-bot
+
+# Test with fake data
+openhome delete --mock
+```
+
+Prompts for confirmation before deleting.
+
+> **Requires session token.** Run `openhome set-jwt <token>` first.
+
+---
+
+### `openhome toggle [ability]`
+
+Enable or disable a deployed ability.
+
+```bash
+# Interactive
+openhome toggle
+
+# By name with flag
+openhome toggle my-weather-bot --enable
+openhome toggle my-weather-bot --disable
+```
+
+| Flag | What it does |
+|------|-------------|
+| `--enable` | Enable the ability |
+| `--disable` | Disable the ability |
+
+> **Requires session token.** Run `openhome set-jwt <token>` first.
+
+---
+
+### `openhome assign`
+
+Assign abilities to an agent (multiselect).
+
+```bash
+openhome assign
+```
+
+Fetches your agents and abilities, lets you pick an agent, then multiselect which abilities to assign to it.
+
+> **Requires session token.** Run `openhome set-jwt <token>` first.
 
 ---
 
@@ -209,12 +230,40 @@ View your agents and set a default for deploys.
 
 ```bash
 openhome agents
+```
 
-# Test with fake data
-openhome agents --mock
+Shows all agents on your account with names and IDs. Optionally set or change your default agent (used by `deploy` when `--personality` is not specified).
+
+---
+
+### `openhome chat [agent]`
+
+Chat with an agent via WebSocket. Send text messages and trigger abilities with keywords.
+
+```bash
+# Pick an agent interactively
+openhome chat
+
+# Chat with a specific agent
+openhome chat pers_abc123
 ```
 
-Shows all agents on your account with names and descriptions. Optionally set or change your default agent (used by `deploy` when `--personality` is not specified).
+Once connected, type messages and press Enter. The agent responds in real-time.
+
+Commands inside chat: `/quit`, `/exit`, or `/q` to disconnect. Ctrl+C also works.
+
+> **Note:** Audio responses from the agent are not playable in the terminal. Text responses display normally.
+
+---
+
+### `openhome trigger [phrase]`
+
+Send a trigger phrase to fire an ability remotely.
+
+```bash
+openhome trigger "play aquaprime"
+openhome trigger --agent pers_abc123 "check weather"
+```
 
 ---
 
@@ -233,9 +282,51 @@ openhome status
 openhome status my-weather-bot --mock
 ```
 
-Shows: name, display name, status, version, timestamps, linked agents, validation errors, and deploy history.
+> **Requires session token** (uses the same list endpoint internally). Run `openhome set-jwt <token>` first.
 
-> **Note:** This endpoint is not yet live. Use `--mock` to preview the output format.
+---
+
+### `openhome logs`
+
+Stream live agent messages and logs.
+
+```bash
+openhome logs
+openhome logs --agent pers_abc123
+```
+
+---
+
+### `openhome whoami`
+
+Show auth status, default agent, and tracked abilities.
+
+```bash
+openhome whoami
+```
+
+---
+
+### `openhome config [path]`
+
+Edit trigger words, description, or category in a local `config.json`.
+
+```bash
+openhome config
+openhome config ./my-ability
+```
+
+---
+
+### `openhome logout`
+
+Clear stored credentials and log out.
+
+```bash
+openhome logout
+```
+
+Removes the API key from macOS Keychain and clears the default agent from config.
 
 ---
 
@@ -259,8 +350,6 @@ Must contain:
 
 ### main.py Required Patterns
 
-Your main Python file must include:
-
 | What | Why |
 |------|-----|
 | Class extending `MatchingCapability` | OpenHome ability base class |
@@ -272,8 +361,6 @@ Your main Python file must include:
 
 ### Blocked Patterns (Errors)
 
-These are not allowed in any `.py` file:
-
 | Pattern | Use Instead |
 |---------|-------------|
 | `print()` | `self.worker.editor_logging_handler` |
@@ -310,8 +397,7 @@ These are not allowed in any `.py` file:
 
 ```
 ~/.openhome/
-  config.json    # Settings + fallback API key
-  last-deploy.zip  # Saved when upload endpoint unavailable
+  config.json    # Settings, fallback API key, session token
 ```
 
 ### Config Fields
@@ -321,6 +407,7 @@ These are not allowed in any `.py` file:
 | `api_base_url` | Override API endpoint | `https://app.openhome.com` |
 | `default_personality_id` | Default agent for deploys | (none) |
 | `api_key` | Fallback key storage | (none — prefers Keychain) |
+| `jwt` | Session token for management commands | (none — set via `set-jwt`) |
 
 ### API Key Storage
 
@@ -328,125 +415,51 @@ On macOS, your API key is stored in the system Keychain (service: `openhome-cli`
 
 ---
 
-## Project Structure
-
-```
-openhome-cli/
-├── bin/openhome.js           # Entry point shim
-├── src/
-│   ├── cli.ts                # Menu + Commander setup
-│   ├── commands/
-│   │   ├── login.ts          # API key auth
-│   │   ├── logout.ts         # Clear credentials
-│   │   ├── init.ts           # Scaffold new ability
-│   │   ├── deploy.ts         # Validate + zip + upload
-│   │   ├── chat.ts           # WebSocket chat with agent
-│   │   ├── list.ts           # List abilities table
-│   │   ├── agents.ts         # View agents + set default
-│   │   └── status.ts         # Ability detail view
-│   ├── api/
-│   │   ├── client.ts         # HTTP client + error handling
-│   │   ├── mock-client.ts    # Fake responses for testing
-│   │   ├── contracts.ts      # TypeScript interfaces
-│   │   └── endpoints.ts      # URL constants
-│   ├── validation/
-│   │   ├── rules.ts          # All validation rules
-│   │   └── validator.ts      # Rule runner
-│   ├── config/
-│   │   ├── store.ts          # Config file + Keychain
-│   │   └── keychain.ts       # macOS Keychain helpers
-│   ├── ui/
-│   │   └── format.ts         # Colors, tables, prompts
-│   └── util/
-│       └── zip.ts            # ZIP creation (archiver)
-└── templates/
-    ├── basic/                # Simple ability template
-    └── api/                  # API-calling ability template
-```
-
----
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run without building (dev mode)
-npm run dev
-
-# Type check
-npm run lint
-
-# Run tests
-npm run test
-```
-
-### Tech Stack
+## What This Tool Does NOT Do
 
-| Package | Version | Purpose |
-|---------|---------|---------|
-| commander | 12.x | CLI argument parsing |
-| @clack/prompts | 1.x | Interactive menus, spinners, prompts |
-| chalk | 5.x | Terminal colors |
-| ws | 8.x | WebSocket client for agent chat |
-| archiver | 7.x | ZIP file creation |
-| typescript | 5.x | Type safety |
-| tsup | 8.x | Build tool |
-| vitest | 2.x | Testing |
+- **No local ability testing** — Abilities run on the OpenHome platform. Deploy and use "Start Live Test" in the web editor to test.
+- **No ability editing** — The CLI does not modify deployed abilities. Edit locally, then re-deploy.
+- **No update/redeploy** — There is no endpoint to overwrite an existing ability version. Deploy creates a new entry; delete the old one via `openhome delete`.
+- **No Windows Keychain** — API key stored in plaintext config on non-macOS platforms.
 
 ---
 
 ## API Status
 
-| Endpoint | Method | Status |
-|----------|--------|--------|
-| `/api/sdk/get_personalities` | POST | Live |
-| `/websocket/voice-stream/{key}/{agent}` | WebSocket | Live |
-| `/api/sdk/abilities` | POST (upload) | Not yet implemented |
-| `/api/sdk/abilities` | GET (list) | Not yet implemented |
-| `/api/sdk/abilities/:id` | GET (detail) | Not yet implemented |
-
-The CLI handles "Not Implemented" responses gracefully. When an endpoint is unavailable:
-- **Deploy**: Saves zip to `~/.openhome/last-deploy.zip` and shows manual upload instructions
-- **List/Status**: Suggests using `--mock` flag to preview the output format
+| Command | Endpoint | Auth | Status |
+|---------|----------|------|--------|
+| `login` | `POST /api/sdk/verify_apikey/` | API key | Live |
+| `agents` | `POST /api/sdk/get_personalities/` | API key | Live |
+| `chat` | WebSocket `/websocket/voice-stream/` | API key | Live |
+| `deploy` | `POST /api/capabilities/add-capability/` | API key | Live |
+| `list` | `GET /api/capabilities/get-installed-capabilities/` | JWT | Live |
+| `delete` | `POST /api/capabilities/delete-capability/` | JWT | Live |
+| `toggle` | `PUT /api/capabilities/edit-installed-capability/:id/` | JWT | Live |
+| `assign` | `PUT /api/personalities/edit-personality/` | JWT | Live |
 
-Use `--mock` on any command to test with fake data while endpoints are being built.
-
----
-
-## What This Tool Does NOT Do
-
-- **No local ability testing** — Abilities run on the OpenHome platform. Deploy and use "Start Live Test" in the web editor to test.
-- **No log streaming** — `openhome logs` is not yet implemented.
-- **No ability deletion** — Must be done through the web dashboard.
-- **No ability editing** — The CLI does not modify deployed abilities. Edit locally, then re-deploy.
-- **No multi-agent deploy** — One ability deploys to one agent at a time.
-- **No Windows Keychain** — API key stored in plaintext config on non-macOS platforms.
+Commands marked **JWT** require `openhome set-jwt <token>` first. OpenHome currently uses separate auth for SDK operations (API key) vs. account management (web session JWT). Once OpenHome adds API key support to management endpoints, the `set-jwt` step will no longer be needed.
 
 ---
 
 ## Roadmap
 
-### Planned
-
-- [ ] `openhome logs [ability]` — Stream ability logs in real-time
-- [ ] `openhome delete [ability]` — Remove a deployed ability
-- [ ] `openhome update` — Re-deploy an existing ability (shortcut for deploy)
 - [ ] `openhome watch` — Auto-deploy on file changes
+- [ ] `openhome update` — Re-deploy/overwrite an existing ability (pending server-side update endpoint)
 - [ ] Background Daemon and Brain Skill templates
 - [ ] Cross-platform secure key storage (Windows Credential Manager, Linux Secret Service)
+- [ ] Management commands without JWT (pending OpenHome API update)
+
+---
 
-### Needs Server-Side Work
+## Development
 
-- [ ] Upload endpoint (`POST /api/sdk/abilities`)
-- [ ] List endpoint (`GET /api/sdk/abilities`)
-- [ ] Detail endpoint (`GET /api/sdk/abilities/:id`)
-- [ ] Log streaming endpoint (WebSocket)
-- [ ] Delete endpoint (`DELETE /api/sdk/abilities/:id`)
+```bash
+npm install
+npm run build      # Build
+npm run dev        # Run without building
+npm run lint       # Type check
+npm run test       # Run tests
+```
 
 ---
 

package/dist/cli.js

@@ -301,24 +301,6 @@ async function loginCommand() {
   }
   saveApiKey(apiKey);
   success("API key saved.");
-  p.note(
-    [
-      "Some features (list, toggle, delete, assign) require a session token.",
-      "To get it: go to app.openhome.com \u2192 open DevTools Console \u2192 run:",
-      "  localStorage.getItem('access_token')"
-    ].join("\n"),
-    "Optional: Session Token"
-  );
-  const jwtInput = await p.text({
-    message: "Paste your session token (or press Enter to skip)",
-    placeholder: "eyJhbGci..."
-  });
-  handleCancel(jwtInput);
-  const jwt = jwtInput?.trim();
-  if (jwt) {
-    saveJwt(jwt);
-    success("Session token saved.");
-  }
   if (agents.length > 0) {
     p.note(
       agents.map((a) => `${chalk2.bold(a.name)}  ${chalk2.gray(a.id)}`).join("\n"),
@@ -1848,6 +1830,12 @@ async function deleteCommand(abilityArg, opts = {}) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com \u2192 DevTools \u2192 Application \u2192 Local Storage \u2192 token\nThen run: openhome set-jwt <token>"
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }
   const s = p.spinner();
@@ -1931,6 +1919,12 @@ async function toggleCommand(abilityArg, opts = {}) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com \u2192 DevTools \u2192 Application \u2192 Local Storage \u2192 token\nThen run: openhome set-jwt <token>"
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }
   const s = p.spinner();
@@ -2024,6 +2018,12 @@ async function assignCommand(opts = {}) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com \u2192 DevTools \u2192 Application \u2192 Local Storage \u2192 token\nThen run: openhome set-jwt <token>"
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }
   const s = p.spinner();
@@ -2127,6 +2127,12 @@ async function listCommand(opts = {}) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com \u2192 DevTools \u2192 Application \u2192 Local Storage \u2192 token\nThen run: openhome set-jwt <token>"
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }
   const s = p.spinner();
@@ -3037,6 +3043,107 @@ async function logsCommand(opts = {}) {
   });
 }
 
+// src/commands/set-jwt.ts
+import { execFile } from "child_process";
+import chalk13 from "chalk";
+var OPENHOME_URL = "https://app.openhome.com";
+function openBrowser(url) {
+  try {
+    if (process.platform === "darwin") {
+      execFile("open", [url]);
+    } else if (process.platform === "win32") {
+      execFile("cmd", ["/c", "start", url]);
+    } else {
+      execFile("xdg-open", [url]);
+    }
+  } catch {
+  }
+}
+async function setJwtCommand(token) {
+  if (token) {
+    p.intro("\u{1F511} Enable Management Features");
+    try {
+      saveJwt(token.trim());
+      success("Session token saved.");
+      p.outro(
+        "Management commands (list, delete, toggle, assign) are now unlocked."
+      );
+    } catch (err) {
+      error(
+        `Failed to save token: ${err instanceof Error ? err.message : String(err)}`
+      );
+      process.exit(1);
+    }
+    return;
+  }
+  p.intro("\u{1F511} Enable Management Features");
+  p.note(
+    [
+      "Some commands (list, delete, enable/disable abilities) need your",
+      "OpenHome session token to work.",
+      "",
+      "Think of it as a temporary key that proves you're logged in to",
+      "your account. You only need to do this once."
+    ].join("\n"),
+    "What's this?"
+  );
+  console.log("");
+  console.log(
+    chalk13.dim(`  Opening ${chalk13.bold("app.openhome.com")} in your browser...`)
+  );
+  openBrowser(OPENHOME_URL);
+  console.log("");
+  p.note(
+    [
+      `${chalk13.bold("Step 1")}  Make sure you're logged in to app.openhome.com`,
+      "",
+      `${chalk13.bold("Step 2")}  Open the browser console:`,
+      `         Mac \u2192 ${chalk13.cyan("Cmd + Option + J")}`,
+      `         Windows / Linux \u2192 ${chalk13.cyan("F12")}, then click the Console tab`,
+      "",
+      `${chalk13.bold("Step 3")}  Paste this command into the console and press Enter:`,
+      "",
+      `         ${chalk13.green("copy(localStorage.getItem('token'))")}`,
+      "",
+      `${chalk13.bold("Step 4")}  Your token is now in your clipboard.`,
+      `         Come back here and paste it below.`
+    ].join("\n"),
+    "How to get your token"
+  );
+  const input = await p.password({
+    message: "Paste your token here",
+    validate: (val) => {
+      if (!val || !val.trim()) return "Token is required";
+      if (val.trim().length < 20)
+        return "That doesn't look right \u2014 the token should be much longer";
+    }
+  });
+  if (typeof input === "symbol") {
+    p.cancel("Cancelled.");
+    return;
+  }
+  try {
+    saveJwt(input.trim());
+    success("Session token saved.");
+    p.note(
+      [
+        "These commands are now unlocked:",
+        `  ${chalk13.bold("openhome list")}    \u2014 see all your deployed abilities`,
+        `  ${chalk13.bold("openhome delete")}  \u2014 remove an ability`,
+        `  ${chalk13.bold("openhome toggle")}  \u2014 enable or disable an ability`,
+        `  ${chalk13.bold("openhome assign")}  \u2014 link abilities to an agent`
+      ].join("\n"),
+      "You're all set"
+    );
+    p.outro("Done!");
+  } catch (err) {
+    error(
+      `Failed to save token: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+}
+
 // src/cli.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
@@ -3124,6 +3231,11 @@ async function interactiveMenu() {
           label: "\u{1F464}  Who Am I",
           hint: "Show auth, default agent, tracked abilities"
         },
+        {
+          value: "set-jwt",
+          label: "\u{1F511}  Enable Management",
+          hint: "Unlock list, delete, toggle, assign"
+        },
         {
           value: "logout",
           label: "\u{1F513}  Log Out",
@@ -3170,6 +3282,9 @@ async function interactiveMenu() {
       case "whoami":
         await whoamiCommand();
         break;
+      case "set-jwt":
+        await setJwtCommand();
+        break;
       case "logout":
         await logoutCommand();
         await ensureLoggedIn();
@@ -3235,6 +3350,11 @@ program.command("logs").description("Stream live agent messages and logs").optio
 program.command("whoami").description("Show auth status, default agent, and tracked abilities").action(async () => {
   await whoamiCommand();
 });
+program.command("set-jwt [token]").description(
+  "Save a session token to enable management commands (list, delete, toggle, assign)"
+).action(async (token) => {
+  await setJwtCommand(token);
+});
 if (process.argv.length <= 2) {
   interactiveMenu().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openhome-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for managing OpenHome voice AI abilities",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -18,6 +18,7 @@ import { triggerCommand } from "./commands/trigger.js";
 import { whoamiCommand } from "./commands/whoami.js";
 import { configEditCommand } from "./commands/config-edit.js";
 import { logsCommand } from "./commands/logs.js";
+import { setJwtCommand } from "./commands/set-jwt.js";
 import { p, handleCancel } from "./ui/format.js";
 
 // Read version from package.json
@@ -115,6 +116,11 @@ async function interactiveMenu(): Promise<void> {
           label: "👤  Who Am I",
           hint: "Show auth, default agent, tracked abilities",
         },
+        {
+          value: "set-jwt",
+          label: "🔑  Enable Management",
+          hint: "Unlock list, delete, toggle, assign",
+        },
         {
           value: "logout",
           label: "🔓  Log Out",
@@ -162,6 +168,9 @@ async function interactiveMenu(): Promise<void> {
       case "whoami":
         await whoamiCommand();
         break;
+      case "set-jwt":
+        await setJwtCommand();
+        break;
       case "logout":
         await logoutCommand();
         await ensureLoggedIn();
@@ -316,6 +325,15 @@ program
     await whoamiCommand();
   });
 
+program
+  .command("set-jwt [token]")
+  .description(
+    "Save a session token to enable management commands (list, delete, toggle, assign)",
+  )
+  .action(async (token?: string) => {
+    await setJwtCommand(token);
+  });
+
 // ── Entry point: menu if no args, subcommand otherwise ───────────
 
 if (process.argv.length <= 2) {

package/src/commands/assign.ts

@@ -20,6 +20,12 @@ export async function assignCommand(
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com → DevTools → Application → Local Storage → token\nThen run: openhome set-jwt <token>",
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }
 

package/src/commands/delete.ts

@@ -21,6 +21,12 @@ export async function deleteCommand(
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com → DevTools → Application → Local Storage → token\nThen run: openhome set-jwt <token>",
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }
 

package/src/commands/list.ts

@@ -36,6 +36,12 @@ export async function listCommand(
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com → DevTools → Application → Local Storage → token\nThen run: openhome set-jwt <token>",
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }
 

package/src/commands/login.ts

@@ -38,28 +38,6 @@ export async function loginCommand(): Promise<void> {
   saveApiKey(apiKey as string);
   success("API key saved.");
 
-  // Ask for JWT for full management access
-  p.note(
-    [
-      "Some features (list, toggle, delete, assign) require a session token.",
-      "To get it: go to app.openhome.com → open DevTools Console → run:",
-      "  localStorage.getItem('access_token')",
-    ].join("\n"),
-    "Optional: Session Token",
-  );
-
-  const jwtInput = await p.text({
-    message: "Paste your session token (or press Enter to skip)",
-    placeholder: "eyJhbGci...",
-  });
-  handleCancel(jwtInput);
-
-  const jwt = (jwtInput as string | undefined)?.trim();
-  if (jwt) {
-    saveJwt(jwt);
-    success("Session token saved.");
-  }
-
   // Show agents on this account
   if (agents.length > 0) {
     p.note(

package/src/commands/set-jwt.ts

@@ -0,0 +1,114 @@
+import { execFile } from "node:child_process";
+import { saveJwt } from "../config/store.js";
+import { success, error, p } from "../ui/format.js";
+import chalk from "chalk";
+
+const OPENHOME_URL = "https://app.openhome.com";
+
+function openBrowser(url: string): void {
+  try {
+    if (process.platform === "darwin") {
+      execFile("open", [url]);
+    } else if (process.platform === "win32") {
+      execFile("cmd", ["/c", "start", url]);
+    } else {
+      execFile("xdg-open", [url]);
+    }
+  } catch {
+    // best-effort — user can open manually
+  }
+}
+
+export async function setJwtCommand(token?: string): Promise<void> {
+  // Direct usage: openhome set-jwt eyJ...
+  if (token) {
+    p.intro("🔑 Enable Management Features");
+    try {
+      saveJwt(token.trim());
+      success("Session token saved.");
+      p.outro(
+        "Management commands (list, delete, toggle, assign) are now unlocked.",
+      );
+    } catch (err) {
+      error(
+        `Failed to save token: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Guided interactive flow
+  p.intro("🔑 Enable Management Features");
+
+  p.note(
+    [
+      "Some commands (list, delete, enable/disable abilities) need your",
+      "OpenHome session token to work.",
+      "",
+      "Think of it as a temporary key that proves you're logged in to",
+      "your account. You only need to do this once.",
+    ].join("\n"),
+    "What's this?",
+  );
+
+  console.log("");
+  console.log(
+    chalk.dim(`  Opening ${chalk.bold("app.openhome.com")} in your browser...`),
+  );
+  openBrowser(OPENHOME_URL);
+  console.log("");
+
+  p.note(
+    [
+      `${chalk.bold("Step 1")}  Make sure you're logged in to app.openhome.com`,
+      "",
+      `${chalk.bold("Step 2")}  Open the browser console:`,
+      `         Mac → ${chalk.cyan("Cmd + Option + J")}`,
+      `         Windows / Linux → ${chalk.cyan("F12")}, then click the Console tab`,
+      "",
+      `${chalk.bold("Step 3")}  Paste this command into the console and press Enter:`,
+      "",
+      `         ${chalk.green("copy(localStorage.getItem('token'))")}`,
+      "",
+      `${chalk.bold("Step 4")}  Your token is now in your clipboard.`,
+      `         Come back here and paste it below.`,
+    ].join("\n"),
+    "How to get your token",
+  );
+
+  const input = await p.password({
+    message: "Paste your token here",
+    validate: (val) => {
+      if (!val || !val.trim()) return "Token is required";
+      if (val.trim().length < 20)
+        return "That doesn't look right — the token should be much longer";
+    },
+  });
+
+  if (typeof input === "symbol") {
+    p.cancel("Cancelled.");
+    return;
+  }
+
+  try {
+    saveJwt((input as string).trim());
+    success("Session token saved.");
+    p.note(
+      [
+        "These commands are now unlocked:",
+        `  ${chalk.bold("openhome list")}    — see all your deployed abilities`,
+        `  ${chalk.bold("openhome delete")}  — remove an ability`,
+        `  ${chalk.bold("openhome toggle")}  — enable or disable an ability`,
+        `  ${chalk.bold("openhome assign")}  — link abilities to an agent`,
+      ].join("\n"),
+      "You're all set",
+    );
+    p.outro("Done!");
+  } catch (err) {
+    error(
+      `Failed to save token: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}

package/src/commands/toggle.ts

@@ -21,6 +21,12 @@ export async function toggleCommand(
       error("Not authenticated. Run: openhome login");
       process.exit(1);
     }
+    if (!jwt) {
+      error(
+        "This command requires a session token.\nGet it from app.openhome.com → DevTools → Application → Local Storage → token\nThen run: openhome set-jwt <token>",
+      );
+      process.exit(1);
+    }
     client = new ApiClient(apiKey, getConfig().api_base_url, jwt);
   }