openhome-cli 0.1.2 → 0.1.4

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

@@ -1,7 +1,7 @@
 import {
   getApiKey,
   getConfig,
-  getJwt as getJwt2,
+  getJwt,
   getTrackedAbilities,
   keychainDelete,
   registerAbility,
@@ -16,6 +16,9 @@ import { fileURLToPath } from "url";
 import { dirname, join as join6 } from "path";
 import { readFileSync as readFileSync5 } from "fs";
 
+// src/commands/login.ts
+import { execFile } from "child_process";
+
 // src/api/endpoints.ts
 var API_BASE = "https://app.openhome.com";
 var WS_BASE = "wss://app.openhome.com";
@@ -272,10 +275,38 @@ function handleCancel(value) {
 
 // src/commands/login.ts
 import chalk2 from "chalk";
+var SETTINGS_URL = "https://app.openhome.com/dashboard/settings";
+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 loginCommand() {
   p.intro("\u{1F511} OpenHome Login");
+  const open = await p.confirm({
+    message: `Press Enter to open your browser and navigate to the ${chalk2.bold("API Keys")} tab`,
+    initialValue: true,
+    active: "Open browser",
+    inactive: "Skip"
+  });
+  handleCancel(open);
+  if (open) {
+    openBrowser(SETTINGS_URL);
+    console.log(
+      `
+  ${chalk2.dim(`Opened ${chalk2.bold("app.openhome.com/dashboard/settings")} \u2014 click the ${chalk2.bold("API Keys")} tab`)}
+`
+    );
+  }
   const apiKey = await p.password({
-    message: "Enter your OpenHome API key",
+    message: "Paste your API key here",
     validate: (val) => {
       if (!val || !val.trim()) return "API key is required";
     }
@@ -548,7 +579,7 @@ import archiver from "archiver";
 import { createWriteStream } from "fs";
 import { Writable } from "stream";
 async function createAbilityZip(dirPath) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve6, reject) => {
     const chunks = [];
     const writable = new Writable({
       write(chunk, _encoding, callback) {
@@ -557,7 +588,7 @@ async function createAbilityZip(dirPath) {
       }
     });
     writable.on("finish", () => {
-      resolve5(Buffer.concat(chunks));
+      resolve6(Buffer.concat(chunks));
     });
     writable.on("error", reject);
     const archive = archiver("zip", { zlib: { level: 9 } });
@@ -1825,7 +1856,7 @@ async function deleteCommand(abilityArg, opts = {}) {
     client = new MockApiClient();
   } else {
     const apiKey = getApiKey() ?? "";
-    const jwt = getJwt2() ?? void 0;
+    const jwt = getJwt() ?? void 0;
     if (!apiKey && !jwt) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
@@ -1914,7 +1945,7 @@ async function toggleCommand(abilityArg, opts = {}) {
     client = new MockApiClient();
   } else {
     const apiKey = getApiKey() ?? "";
-    const jwt = getJwt2() ?? void 0;
+    const jwt = getJwt() ?? void 0;
     if (!apiKey && !jwt) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
@@ -2013,7 +2044,7 @@ async function assignCommand(opts = {}) {
     client = new MockApiClient();
   } else {
     const apiKey = getApiKey() ?? "";
-    const jwt = getJwt2() ?? void 0;
+    const jwt = getJwt() ?? void 0;
     if (!apiKey && !jwt) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
@@ -2122,7 +2153,7 @@ async function listCommand(opts = {}) {
     client = new MockApiClient();
   } else {
     const apiKey = getApiKey() ?? "";
-    const jwt = getJwt2() ?? void 0;
+    const jwt = getJwt() ?? void 0;
     if (!apiKey && !jwt) {
       error("Not authenticated. Run: openhome login");
       process.exit(1);
@@ -2422,7 +2453,7 @@ async function chatCommand(agentArg, opts = {}) {
   }
   const wsUrl = `${WS_BASE}${ENDPOINTS.voiceStream(apiKey, agentId)}`;
   info(`Connecting to agent ${chalk9.bold(agentId)}...`);
-  await new Promise((resolve5) => {
+  await new Promise((resolve6) => {
     const ws = new WebSocket(wsUrl, {
       perMessageDeflate: false,
       headers: {
@@ -2550,7 +2581,7 @@ async function chatCommand(agentArg, opts = {}) {
       console.error("");
       error(`WebSocket error: ${err.message}`);
       rl.close();
-      resolve5();
+      resolve6();
     });
     ws.on("close", (code) => {
       if (pingInterval) clearInterval(pingInterval);
@@ -2561,7 +2592,7 @@ async function chatCommand(agentArg, opts = {}) {
         info(`Connection closed (code: ${code})`);
       }
       rl.close();
-      resolve5();
+      resolve6();
     });
     rl.on("close", () => {
       if (connected) {
@@ -2628,7 +2659,7 @@ async function triggerCommand(phraseArg, opts = {}) {
   info(`Sending "${chalk10.bold(phrase)}" to agent ${chalk10.bold(agentId)}...`);
   const s = p.spinner();
   s.start("Waiting for response...");
-  await new Promise((resolve5) => {
+  await new Promise((resolve6) => {
     const ws = new WebSocket2(wsUrl, {
       perMessageDeflate: false,
       headers: {
@@ -2658,7 +2689,7 @@ async function triggerCommand(phraseArg, opts = {}) {
 ${chalk10.cyan("Agent:")} ${fullResponse}`);
         }
         cleanup();
-        resolve5();
+        resolve6();
       }, RESPONSE_TIMEOUT);
     });
     ws.on("message", (raw) => {
@@ -2675,7 +2706,7 @@ ${chalk10.cyan("Agent:")} ${fullResponse}`);
 ${chalk10.cyan("Agent:")} ${fullResponse}
 `);
                 cleanup();
-                resolve5();
+                resolve6();
               }
             }
             break;
@@ -2692,7 +2723,7 @@ ${chalk10.cyan("Agent:")} ${fullResponse}
 ${chalk10.cyan("Agent:")} ${fullResponse}
 `);
                 cleanup();
-                resolve5();
+                resolve6();
               }
             }
             break;
@@ -2707,7 +2738,7 @@ ${chalk10.cyan("Agent:")} ${fullResponse}
               `Server error: ${errData?.message || errData?.title || "Unknown"}`
             );
             cleanup();
-            resolve5();
+            resolve6();
             break;
           }
         }
@@ -2717,12 +2748,12 @@ ${chalk10.cyan("Agent:")} ${fullResponse}
     ws.on("error", (err) => {
       s.stop("Connection error.");
       error(err.message);
-      resolve5();
+      resolve6();
     });
     ws.on("close", () => {
       if (pingInterval) clearInterval(pingInterval);
       if (responseTimer) clearTimeout(responseTimer);
-      resolve5();
+      resolve6();
     });
   });
 }
@@ -2947,7 +2978,7 @@ async function logsCommand(opts = {}) {
   info(`Streaming logs from agent ${chalk12.bold(agentId)}...`);
   info(`Press ${chalk12.bold("Ctrl+C")} to stop.
 `);
-  await new Promise((resolve5) => {
+  await new Promise((resolve6) => {
     const ws = new WebSocket3(wsUrl, {
       perMessageDeflate: false,
       headers: {
@@ -3027,13 +3058,13 @@ async function logsCommand(opts = {}) {
     });
     ws.on("error", (err) => {
       error(`WebSocket error: ${err.message}`);
-      resolve5();
+      resolve6();
     });
     ws.on("close", (code) => {
       if (pingInterval) clearInterval(pingInterval);
       console.log("");
       info(`Connection closed (code: ${code})`);
-      resolve5();
+      resolve6();
     });
     process.on("SIGINT", () => {
       console.log("");
@@ -3044,33 +3075,98 @@ async function logsCommand(opts = {}) {
 }
 
 // src/commands/set-jwt.ts
+import { execFile as execFile2 } from "child_process";
+import chalk13 from "chalk";
+var OPENHOME_URL = "https://app.openhome.com";
+function openBrowser2(url) {
+  try {
+    if (process.platform === "darwin") {
+      execFile2("open", [url]);
+    } else if (process.platform === "win32") {
+      execFile2("cmd", ["/c", "start", url]);
+    } else {
+      execFile2("xdg-open", [url]);
+    }
+  } catch {
+  }
+}
 async function setJwtCommand(token) {
-  p.intro("\u{1F511} Set Session Token");
-  let jwt = token;
-  if (!jwt) {
-    const input = await p.text({
-      message: "Paste your OpenHome session token",
-      placeholder: "eyJ...",
-      validate: (val) => {
-        if (!val || !val.trim()) return "Token is required";
-        if (!val.trim().startsWith("eyJ"))
-          return "Doesn't look like a JWT \u2014 should start with eyJ";
-      }
-    });
-    if (typeof input === "symbol") {
-      p.cancel("Cancelled.");
-      return;
+  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...`)
+  );
+  openBrowser2(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";
     }
-    jwt = input;
+  });
+  if (typeof input === "symbol") {
+    p.cancel("Cancelled.");
+    return;
   }
   try {
-    saveJwt(jwt.trim());
+    saveJwt(input.trim());
     success("Session token saved.");
     p.note(
-      "Management commands (list, delete, toggle, assign) are now unlocked.",
-      "Token saved"
+      [
+        "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.");
+    p.outro("Done!");
   } catch (err) {
     error(
       `Failed to save token: ${err instanceof Error ? err.message : String(err)}`
@@ -3079,6 +3175,45 @@ async function setJwtCommand(token) {
   }
 }
 
+// src/commands/validate.ts
+import { resolve as resolve5 } from "path";
+import chalk14 from "chalk";
+async function validateCommand(pathArg = ".") {
+  const targetDir = resolve5(pathArg);
+  p.intro(`\u{1F50E} Validate ability`);
+  const s = p.spinner();
+  s.start("Running checks...");
+  const result = validateAbility(targetDir);
+  if (result.errors.length === 0 && result.warnings.length === 0) {
+    s.stop("All checks passed.");
+    p.outro("Ability is ready to deploy! \u{1F389}");
+    return;
+  }
+  s.stop("Checks complete.");
+  if (result.errors.length > 0) {
+    p.note(
+      result.errors.map(
+        (issue) => `${chalk14.red("\u2717")} ${issue.file ? chalk14.bold(`[${issue.file}]`) + " " : ""}${issue.message}`
+      ).join("\n"),
+      `${result.errors.length} Error(s)`
+    );
+  }
+  if (result.warnings.length > 0) {
+    p.note(
+      result.warnings.map(
+        (w) => `${chalk14.yellow("\u26A0")} ${w.file ? chalk14.bold(`[${w.file}]`) + " " : ""}${w.message}`
+      ).join("\n"),
+      `${result.warnings.length} Warning(s)`
+    );
+  }
+  if (result.passed) {
+    p.outro("Validation passed (with warnings).");
+  } else {
+    error("Fix errors before deploying.");
+    process.exit(1);
+  }
+}
+
 // src/cli.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
@@ -3111,16 +3246,6 @@ async function interactiveMenu() {
           label: "\u2728  Create Ability",
           hint: "Scaffold and deploy a new ability"
         },
-        {
-          value: "chat",
-          label: "\u{1F4AC}  Chat",
-          hint: "Talk to your agent"
-        },
-        {
-          value: "trigger",
-          label: "\u26A1  Trigger",
-          hint: "Fire an ability remotely with a phrase"
-        },
         {
           value: "list",
           label: "\u{1F4CB}  My Abilities",
@@ -3147,25 +3272,15 @@ async function interactiveMenu() {
           hint: "View agents and set default"
         },
         {
-          value: "status",
-          label: "\u{1F50D}  Status",
-          hint: "Check ability status"
-        },
-        {
-          value: "config",
-          label: "\u2699\uFE0F   Edit Config",
-          hint: "Update trigger words, description, category"
+          value: "chat",
+          label: "\u{1F4AC}  Chat",
+          hint: "Talk to your agent"
         },
         {
           value: "logs",
           label: "\u{1F4E1}  Logs",
           hint: "Stream live agent messages"
         },
-        {
-          value: "whoami",
-          label: "\u{1F464}  Who Am I",
-          hint: "Show auth, default agent, tracked abilities"
-        },
         {
           value: "logout",
           label: "\u{1F513}  Log Out",
@@ -3179,12 +3294,6 @@ async function interactiveMenu() {
       case "init":
         await initCommand();
         break;
-      case "chat":
-        await chatCommand();
-        break;
-      case "trigger":
-        await triggerCommand();
-        break;
       case "list":
         await listCommand();
         break;
@@ -3200,18 +3309,12 @@ async function interactiveMenu() {
       case "agents":
         await agentsCommand();
         break;
-      case "status":
-        await statusCommand();
-        break;
-      case "config":
-        await configEditCommand();
+      case "chat":
+        await chatCommand();
         break;
       case "logs":
         await logsCommand();
         break;
-      case "whoami":
-        await whoamiCommand();
-        break;
       case "logout":
         await logoutCommand();
         await ensureLoggedIn();
@@ -3277,6 +3380,9 @@ 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("validate [path]").description("Check an ability for errors before deploying").action(async (path) => {
+  await validateCommand(path);
+});
 program.command("set-jwt [token]").description(
   "Save a session token to enable management commands (list, delete, toggle, assign)"
 ).action(async (token) => {

package/package.json

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

package/src/cli.ts

@@ -19,6 +19,7 @@ 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 { validateCommand } from "./commands/validate.js";
 import { p, handleCancel } from "./ui/format.js";
 
 // Read version from package.json
@@ -61,16 +62,6 @@ async function interactiveMenu(): Promise<void> {
           label: "✨  Create Ability",
           hint: "Scaffold and deploy a new ability",
         },
-        {
-          value: "chat",
-          label: "💬  Chat",
-          hint: "Talk to your agent",
-        },
-        {
-          value: "trigger",
-          label: "⚡  Trigger",
-          hint: "Fire an ability remotely with a phrase",
-        },
         {
           value: "list",
           label: "📋  My Abilities",
@@ -97,25 +88,15 @@ async function interactiveMenu(): Promise<void> {
           hint: "View agents and set default",
         },
         {
-          value: "status",
-          label: "🔍  Status",
-          hint: "Check ability status",
-        },
-        {
-          value: "config",
-          label: "⚙️   Edit Config",
-          hint: "Update trigger words, description, category",
+          value: "chat",
+          label: "💬  Chat",
+          hint: "Talk to your agent",
         },
         {
           value: "logs",
           label: "📡  Logs",
           hint: "Stream live agent messages",
         },
-        {
-          value: "whoami",
-          label: "👤  Who Am I",
-          hint: "Show auth, default agent, tracked abilities",
-        },
         {
           value: "logout",
           label: "🔓  Log Out",
@@ -130,12 +111,6 @@ async function interactiveMenu(): Promise<void> {
       case "init":
         await initCommand();
         break;
-      case "chat":
-        await chatCommand();
-        break;
-      case "trigger":
-        await triggerCommand();
-        break;
       case "list":
         await listCommand();
         break;
@@ -151,18 +126,12 @@ async function interactiveMenu(): Promise<void> {
       case "agents":
         await agentsCommand();
         break;
-      case "status":
-        await statusCommand();
-        break;
-      case "config":
-        await configEditCommand();
+      case "chat":
+        await chatCommand();
         break;
       case "logs":
         await logsCommand();
         break;
-      case "whoami":
-        await whoamiCommand();
-        break;
       case "logout":
         await logoutCommand();
         await ensureLoggedIn();
@@ -317,6 +286,13 @@ program
     await whoamiCommand();
   });
 
+program
+  .command("validate [path]")
+  .description("Check an ability for errors before deploying")
+  .action(async (path?: string) => {
+    await validateCommand(path);
+  });
+
 program
   .command("set-jwt [token]")
   .description(

package/src/commands/login.ts

@@ -1,14 +1,46 @@
+import { execFile } from "node:child_process";
 import { ApiClient } from "../api/client.js";
 import type { Personality } from "../api/contracts.js";
-import { saveApiKey, saveJwt } from "../config/store.js";
+import { saveApiKey } from "../config/store.js";
 import { success, error, info, p, handleCancel } from "../ui/format.js";
 import chalk from "chalk";
 
+const SETTINGS_URL = "https://app.openhome.com/dashboard/settings";
+
+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
+  }
+}
+
 export async function loginCommand(): Promise<void> {
   p.intro("🔑 OpenHome Login");
 
+  const open = await p.confirm({
+    message: `Press Enter to open your browser and navigate to the ${chalk.bold("API Keys")} tab`,
+    initialValue: true,
+    active: "Open browser",
+    inactive: "Skip",
+  });
+  handleCancel(open);
+
+  if (open) {
+    openBrowser(SETTINGS_URL);
+    console.log(
+      `\n  ${chalk.dim(`Opened ${chalk.bold("app.openhome.com/dashboard/settings")} — click the ${chalk.bold("API Keys")} tab`)}\n`,
+    );
+  }
+
   const apiKey = await p.password({
-    message: "Enter your OpenHome API key",
+    message: "Paste your API key here",
     validate: (val) => {
       if (!val || !val.trim()) return "API key is required";
     },
@@ -38,7 +70,6 @@ export async function loginCommand(): Promise<void> {
   saveApiKey(apiKey as string);
   success("API key saved.");
 
-  // Show agents on this account
   if (agents.length > 0) {
     p.note(
       agents

package/src/commands/set-jwt.ts

@@ -1,36 +1,110 @@
+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> {
-  p.intro("🔑 Set Session Token");
-
-  let jwt = token;
-
-  if (!jwt) {
-    const input = await p.text({
-      message: "Paste your OpenHome session token",
-      placeholder: "eyJ...",
-      validate: (val) => {
-        if (!val || !val.trim()) return "Token is required";
-        if (!val.trim().startsWith("eyJ"))
-          return "Doesn't look like a JWT — should start with eyJ";
-      },
-    });
-    if (typeof input === "symbol") {
-      p.cancel("Cancelled.");
-      return;
+  // 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);
     }
-    jwt = input;
+    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(jwt.trim());
+    saveJwt((input as string).trim());
     success("Session token saved.");
     p.note(
-      "Management commands (list, delete, toggle, assign) are now unlocked.",
-      "Token saved",
+      [
+        "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.");
+    p.outro("Done!");
   } catch (err) {
     error(
       `Failed to save token: ${err instanceof Error ? err.message : String(err)}`,

package/src/commands/status.ts

@@ -3,7 +3,12 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { ApiClient, NotImplementedError } from "../api/client.js";
 import { MockApiClient } from "../api/mock-client.js";
-import { getApiKey, getConfig, getTrackedAbilities } from "../config/store.js";
+import {
+  getApiKey,
+  getConfig,
+  getJwt,
+  getTrackedAbilities,
+} from "../config/store.js";
 import { error, warn, info, p, handleCancel } from "../ui/format.js";
 import chalk from "chalk";