callkaro-cli-unofficial 0.2.0 → 0.3.0

package/README.md

@@ -1,260 +1,260 @@
-# cku
-
-An unofficial fork of the [CallKaro CLI](https://www.npmjs.com/package/@callkaro-official/cli). It installs as `cku`, so it sits alongside the official `ck` without either one overwriting the other.
-
-Manage voice agents, calls, phone numbers, batch campaigns, simulations and analytics from the terminal — plus the dashboard side, which the official CLI doesn't reach at all.
-
-```
-cku agents list
-cku calls make --agent <id> --to <number> --test
-cku kpi tasks --severity "Very High" --column action_items
-cku accounts use tejas@acme.com
-```
-
----
-
-## Why this exists
-
-**It doesn't fight the official CLI for a name.** Both packages write to the same global `node_modules/.bin`. If both were called `ck`, whichever npm install ran last would silently take over. You'd type `ck`, get official behaviour, and get no signal anything had changed. `cku` cannot collide.
-
-**It holds several accounts at once.** The official CLI keeps one session. This one keeps a file per account, and can pin an account to a folder, so two agents working in two directories can't switch each other out from under themselves.
-
-**It reaches the dashboard API.** The official CLI only talks to `/cli/*`. That leaves the KPI board, the call analyzers, and the server's own model catalogue unreachable from a terminal — [`cku kpi`](#only-in-cku) is the whole of that surface.
-
-**It fixes three upstream bugs.** Details and evidence in [`docs/BUG-REPORT.md`](docs/BUG-REPORT.md).
-
----
-
-## Install
-
-```bash
-npm install --global callkaro-cli-unofficial
-```
-
-Or, to work on it directly:
-
-```bash
-git clone https://github.com/TejasLamba2006/callkaro-cli-unofficial
-cd callkaro-cli-unofficial
-npm install && npm run build && npm link
-```
-
-Node 18 or newer.
-
----
-
-## How it fits together
-
-![Runtime flow: cku commands through the shared layer to the backend, config, and the skill pack](docs/images/runtime-flow.webp)
-
-Every arrow above is a real import or a real call, checked against the source. `api.ts` is the only thing that touches the network. `config.ts` is the only thing that reads a token, which is why every route to the backend goes through it. The ASCII version below says the same thing for the terminal:
-
-```
-┌─ cku ─────────────────────────────────────────────┐
-│  index.ts     commander wiring, 44 subcommands     │
-│     ↓                                             │
-│  commands/    agents, calls, numbers, batches,     │
-│               sim, analytics, audits, skills       │
-│     ↓                                             │
-│  lib/         api.ts, config.ts, agentUpdate.ts,   │
-│               looseJson.ts, ui.ts, catalog.ts     │
-└──────┬────────────────────────────────────────────┘
-       ↓
-  account resolution, highest precedence first
-       │
-  CK_TOKEN → CK_ACCOUNT → ./.cku.json → global → none
-       │
-       ↓
-  backend.callkaro.ai
-  /cli/*  ·  61 endpoints  ·  Bearer ck_5b02…
-```
-
-One thing worth knowing up front: the official CLI ships **compiled output only**. Its npm package has `dist/` and nothing else: no TypeScript, no tests, no build config, and it isn't in any public repo. So this is a reconstruction. The `/cli/*` contract was rebuilt from the published bundle, and the command surface matches v4.0.1 (the official CLI's commands plus the `accounts` group and the dashboard-side `dashboard`, `kpi`, `analyzers` and `models` groups).
-
-The public API at `api.callkaro.ai` is a different thing entirely, with an `X-API-KEY` header and three documented endpoints. This CLI doesn't use it. [`docs/architecture.md`](docs/architecture.md) covers the boundaries, and [`docs/api.md`](docs/api.md) has the full endpoint inventory.
-
----
-
-## Several accounts
-
-```bash
-cku login                              # add an account
-cku accounts                           # list them, * marks the active one
-cku accounts use <email>               # change the global default
-cku accounts remove <email>            # forget one
-```
-
-### Pin an account to a folder
-
-If you're running more than one agent at a time, this is the part that matters.
-
-```bash
-cd ~/work/bot-alpha && cku accounts bind alpha@acme.com
-cd ~/work/bot-beta  && cku accounts bind beta@other.com
-```
-
-`bind` writes a `.cku.json` into that directory containing just the account slug and no token, so it's safe to commit. Every `cku` command in that folder (and anything nested under it) uses that account, regardless of what the global default says.
-
-Why this matters: `cku accounts use` changes **shared** state. Two agents in two folders both calling it would overwrite each other, and whichever wrote last would silently redirect the other bot's commands to the wrong CallKaro account. No error, just wrong data. A bound folder never reads shared state at all, so that can't happen.
-
-```
-cku accounts status
-```
-
-tells you which account is in effect *and where the choice came from*: env var, this folder, or the global default. Worth running first when something looks off, since acting on the wrong account is the most damaging mistake available here.
-
-Override for a single command with `CK_ACCOUNT=<email> cku whoami`.
-
----
-
-## Fixes over the official CLI
-
-Full write-ups, with line numbers and reproduction steps, in [`docs/BUG-REPORT.md`](docs/BUG-REPORT.md).
-
-**`agents update --set` silently deleted agent configuration.** Send a partial `voice_configuration` and the backend replaces the whole object, so nine keys, including the voice itself, were dropped, and the command reported success. The agent kept working; it just couldn't make calls. The fix already exists upstream as `deepMerge`, with a comment describing exactly this problem. Nothing ever called it.
-
-**`skills install` failed on every run on Windows.** `tar` was handed an absolute path, and `C:/Users/...` gets read as a `<host>:<path>` remote spec, so tar tried to connect to a machine named "C". Since the temp path always sits under a drive root, this never worked there. It's also the only way to install the skill pack, so an agent couldn't bootstrap itself on Windows. Linux and macOS were never affected; no drive letters, no colon in a path.
-
-**`agents export` can't always be re-imported.** For some agents the export response omits a field the CLI's own validator requires, so the round trip fails. That part needs a backend fix; a workaround is in the `callkaro-cli` skill.
-
-My own first port of this fix had a worse version of the same bug: I merged against the agent's default version, so updating any other version could swap its voice for the default's. That's fixed and covered by a test, and the details are in [`docs/official-fixes.md`](docs/official-fixes.md).
-
----
-
-## Only in `cku`
-
-Commands and capabilities the official CLI does not have at all. Not bug fixes — surface area.
-
-### The KPI manager and the pending-task board
-
-The official `ck` has **no KPI commands whatsoever**. This is the only way to reach the board from a terminal.
-
-```bash
-cku kpi tasks --severity "Very High" --column action_items --since 7d
-cku kpi show "<taskId>"                 # cause, recommended fix, metric impact
-cku kpi create --cause "…" --fix "…" --severity High
-cku kpi move "<taskId>" in_progress
-cku kpi comment "<taskId>" "Fixed in v3"
-cku kpi assign "<taskId>" --to "Name"   # or --to ai_fde
-cku kpi target --agent <id> --value 25
-cku kpi rca --agent <id> --since 2026-09-01 --until 2026-09-30
-```
-
-There is **no delete** for a card — the board retires one by moving it to `rejected`, which is reversible. Only `description` is editable after creation; `cause`, fix and severity are fixed at create, so correcting one means creating a replacement.
-
-`GET /pending-tasks` returns every column including `done` and `rejected`, so a closed card is not a gone card. The list prints a **COLUMN** column for exactly that reason, and `--column` filters on it.
-
-### The dashboard credential
-
-```bash
-cku dashboard login     # separate from `cku login`; the token lasts 24h, renewed silently
-cku dashboard whoami
-cku dashboard probe     # which dashboard routes this token reaches
-```
-
-The dashboard API needs a *different* token from `/cli/*` — they're not interchangeable, and each rejects the other with an opaque 401. This also unlocks `cku analyzers` and `cku models`. The dashboard token expires every 24h with no refresh endpoint, so `cku dashboard login` saves your password (plain text, mode 0600, alongside the tokens) and re-logs in for you when it lapses. Pass `--no-save-password` to keep it off disk and re-enter it daily; `cku dashboard logout` deletes it.
-
-### Knowing which models are actually valid
-
-```bash
-cku models               # per slot, and which field each governs
-cku models --slot agent
-```
-
-Models are scoped per slot and **the slots disagree**: `agent` has 44, `post-call` has 9 and excludes `gpt-4o` and `o4-mini`. So the same value is valid in `model` and refused in `postcallmodel`. Works with or without a dashboard session, and says which source it read.
-
-### A catalogue that can't silently rot
-
-The provider tables, and now the model lists, are regenerated from the server rather than hand-copied:
-
-```bash
-npm run catalog:sync     # refresh from the bundle + the live server
-npm run catalog:check    # fail if catalog.json disagrees with the snapshot
-```
-
-`catalog:check` runs offline against a committed snapshot, so it works in CI with no credentials. On 1 October 2026 it caught shipped tables that listed withdrawn models *and* missed live ones in both directions. A wrong voice model otherwise persists silently and only surfaces as a broken call.
-
-### Smaller things
-
-- `cku calls logs` — grep/awk/sed over the raw call log, in-process, no subprocess and no shell
-- `cku accounts status` — reports which account is in effect **and where that choice came from**
-- Per-project binding, so parallel agents can't redirect each other
-- `secrets set` without the value on the command line
-- `--json` that stays unpaged for scripting, with human tables paged
-
----
-
-## Staying current
-
-A daily workflow checks npm for a newer `@callkaro-official/cli` and, when it finds one, regenerates the provider catalogue and opens a PR onto the `official` branch. It never merges anything itself.
-
-| Branch | What's on it |
-|---|---|
-| `official` | Clean base. Changes only arrive through sync PRs. |
-| `main` | `official` plus your customizations. Your working branch. |
-
-To take an update: review the PR, merge into `official`, then merge `official` into `main`.
-
-Worth knowing what the sync does and doesn't do. It regenerates `src/data/catalog.json` — the provider tables and the per-slot LLM model lists — because those change when the dashboard changes. It does **not** port command code, because the official source isn't available, so that's maintained by hand. The PR lists which commands were added or removed so you know what to look at.
-
-Keep your customizations in as few files as you can. That diff is the one you have to resolve on every update.
-
----
-
-## Development
-
-```bash
-npm run build          # tsc -> dist/, copy endpoints.json, chmod +x
-npm test               # build, then node --test
-npm run test:only      # tests without rebuilding
-npm run dev            # build and run
-npm run catalog:sync   # regenerate the catalogue: provider tables + per-slot LLM lists, from the server
-npm run catalog:check  # fail if catalog.json disagrees with the server snapshot (offline)
-npm run catalog:check:live  # same, against the live server (needs `cku dashboard login`)
-```
-
-Single test file:
-
-```bash
-node --test tests/agentUpdate.test.js
-```
-
-210 tests. No linter or formatter is configured.
-
-### Layout
-
-`src/index.ts` is commander wiring and almost nothing else. Every command, flag and description is declared there. `src/commands/` holds one module per command group. `src/lib/` holds the shared layer, and that's where the rules worth knowing live:
-
-- **`api.ts`** is the only place that talks to the backend. Adding an endpoint means adding a method here, not a raw `fetch` in a command.
-- **`looseJson.ts`** has two parsers, chosen by where the text came from. Values from argv get a repair pass, because PowerShell strips quotes out of single-quoted arguments and `--set '{"name":"x"}'` arrives as `{name:x}`. Values from files or stdin are parsed strictly, since the shell never touched them and a real typo should be reported rather than guessed at.
-- **`agentUpdate.ts`** merges updates into objects the backend replaces wholesale, so a partial update doesn't drop its siblings.
-- **`ui.ts`** sets `process.exitCode` rather than calling `process.exit()`. On Windows, exiting while a fetch socket is still closing trips a libuv assertion that aborts with code 127 and a pile of C-level noise.
-
-### Regenerating docs
-
-Both of these read from the code, so they can't drift:
-
-```bash
-node scripts/gen-api-inventory.js          # endpoint tables in docs/api.md
-node scripts/gen-cli-reference.js ../callkaro-skills/skills/callkaro-cli/REFERENCE.md
-```
-
----
-
-## Skills
-
-The CLI installs a skill pack for Claude Code and other coding agents, so an agent can drive `cku` without being told how.
-
-```bash
-cku skills install --claude          # this fork's pack
-cku skills install --claude --official   # the upstream pack
-cku skills update                    # refresh every install
-```
-
-Targets include `--cursor --copilot --gemini --windsurf --roo --opencode --cline --codex --all`, plus `--project` to install into a repo rather than your user account. Skills ship from GitHub, so a new one reaches users without a CLI release.
-
----
-
-## License
-
-Apache-2.0, matching the upstream CLI.
+# cku
+
+An unofficial fork of the [CallKaro CLI](https://www.npmjs.com/package/@callkaro-official/cli). It installs as `cku`, so it sits alongside the official `ck` without either one overwriting the other.
+
+Manage voice agents, calls, phone numbers, batch campaigns, simulations and analytics from the terminal — plus the dashboard side, which the official CLI doesn't reach at all.
+
+```
+cku agents list
+cku calls make --agent <id> --to <number> --test
+cku kpi tasks --severity "Very High" --column action_items
+cku accounts use tejas@acme.com
+```
+
+---
+
+## Why this exists
+
+**It doesn't fight the official CLI for a name.** Both packages write to the same global `node_modules/.bin`. If both were called `ck`, whichever npm install ran last would silently take over. You'd type `ck`, get official behaviour, and get no signal anything had changed. `cku` cannot collide.
+
+**It holds several accounts at once.** The official CLI keeps one session. This one keeps a file per account, and can pin an account to a folder, so two agents working in two directories can't switch each other out from under themselves.
+
+**It reaches the dashboard API.** The official CLI only talks to `/cli/*`. That leaves the KPI board, the call analyzers, and the server's own model catalogue unreachable from a terminal — [`cku kpi`](#only-in-cku) is the whole of that surface.
+
+**It fixes three upstream bugs.** Details and evidence in [`docs/BUG-REPORT.md`](docs/BUG-REPORT.md).
+
+---
+
+## Install
+
+```bash
+npm install --global callkaro-cli-unofficial
+```
+
+Or, to work on it directly:
+
+```bash
+git clone https://github.com/TejasLamba2006/callkaro-cli-unofficial
+cd callkaro-cli-unofficial
+npm install && npm run build && npm link
+```
+
+Node 18 or newer.
+
+---
+
+## How it fits together
+
+![Runtime flow: cku commands through the shared layer to the backend, config, and the skill pack](docs/images/runtime-flow.webp)
+
+Every arrow above is a real import or a real call, checked against the source. `api.ts` is the only thing that touches the network. `config.ts` is the only thing that reads a token, which is why every route to the backend goes through it. The ASCII version below says the same thing for the terminal:
+
+```
+┌─ cku ─────────────────────────────────────────────┐
+│  index.ts     commander wiring, 44 subcommands     │
+│     ↓                                             │
+│  commands/    agents, calls, numbers, batches,     │
+│               sim, analytics, audits, skills       │
+│     ↓                                             │
+│  lib/         api.ts, config.ts, agentUpdate.ts,   │
+│               looseJson.ts, ui.ts, catalog.ts     │
+└──────┬────────────────────────────────────────────┘
+       ↓
+  account resolution, highest precedence first
+       │
+  CK_TOKEN → CK_ACCOUNT → ./.cku.json → global → none
+       │
+       ↓
+  backend.callkaro.ai
+  /cli/*  ·  61 endpoints  ·  Bearer ck_5b02…
+```
+
+One thing worth knowing up front: the official CLI ships **compiled output only**. Its npm package has `dist/` and nothing else: no TypeScript, no tests, no build config, and it isn't in any public repo. So this is a reconstruction. The `/cli/*` contract was rebuilt from the published bundle, and the command surface matches v5.0.0 (the official CLI's commands, its `accounts` group renamed `monitor`, plus the `accounts` group and the dashboard-side `dashboard`, `kpi`, `analyzers` and `models` groups).
+
+The public API at `api.callkaro.ai` is a different thing entirely, with an `X-API-KEY` header and three documented endpoints. This CLI doesn't use it. [`docs/architecture.md`](docs/architecture.md) covers the boundaries, and [`docs/api.md`](docs/api.md) has the full endpoint inventory.
+
+---
+
+## Several accounts
+
+```bash
+cku login                              # add an account
+cku accounts                           # list them, * marks the active one
+cku accounts use <email>               # change the global default
+cku accounts remove <email>            # forget one
+```
+
+### Pin an account to a folder
+
+If you're running more than one agent at a time, this is the part that matters.
+
+```bash
+cd ~/work/bot-alpha && cku accounts bind alpha@acme.com
+cd ~/work/bot-beta  && cku accounts bind beta@other.com
+```
+
+`bind` writes a `.cku.json` into that directory containing just the account slug and no token, so it's safe to commit. Every `cku` command in that folder (and anything nested under it) uses that account, regardless of what the global default says.
+
+Why this matters: `cku accounts use` changes **shared** state. Two agents in two folders both calling it would overwrite each other, and whichever wrote last would silently redirect the other bot's commands to the wrong CallKaro account. No error, just wrong data. A bound folder never reads shared state at all, so that can't happen.
+
+```
+cku accounts status
+```
+
+tells you which account is in effect *and where the choice came from*: env var, this folder, or the global default. Worth running first when something looks off, since acting on the wrong account is the most damaging mistake available here.
+
+Override for a single command with `CK_ACCOUNT=<email> cku whoami`.
+
+---
+
+## Fixes over the official CLI
+
+Full write-ups, with line numbers and reproduction steps, in [`docs/BUG-REPORT.md`](docs/BUG-REPORT.md).
+
+**`agents update --set` silently deleted agent configuration.** Send a partial `voice_configuration` and the backend replaces the whole object, so nine keys, including the voice itself, were dropped, and the command reported success. The agent kept working; it just couldn't make calls. The fix already exists upstream as `deepMerge`, with a comment describing exactly this problem. Nothing ever called it.
+
+**`skills install` failed on every run on Windows.** `tar` was handed an absolute path, and `C:/Users/...` gets read as a `<host>:<path>` remote spec, so tar tried to connect to a machine named "C". Since the temp path always sits under a drive root, this never worked there. It's also the only way to install the skill pack, so an agent couldn't bootstrap itself on Windows. Linux and macOS were never affected; no drive letters, no colon in a path.
+
+**`agents export` can't always be re-imported.** For some agents the export response omits a field the CLI's own validator requires, so the round trip fails. That part needs a backend fix; a workaround is in the `callkaro-cli` skill.
+
+My own first port of this fix had a worse version of the same bug: I merged against the agent's default version, so updating any other version could swap its voice for the default's. That's fixed and covered by a test, and the details are in [`docs/official-fixes.md`](docs/official-fixes.md).
+
+---
+
+## Only in `cku`
+
+Commands and capabilities the official CLI does not have at all. Not bug fixes — surface area.
+
+### The KPI manager and the pending-task board
+
+The official `ck` has **no KPI commands whatsoever**. This is the only way to reach the board from a terminal.
+
+```bash
+cku kpi tasks --severity "Very High" --column action_items --since 7d
+cku kpi show "<taskId>"                 # cause, recommended fix, metric impact
+cku kpi create --cause "…" --fix "…" --severity High
+cku kpi move "<taskId>" in_progress
+cku kpi comment "<taskId>" "Fixed in v3"
+cku kpi assign "<taskId>" --to "Name"   # or --to ai_fde
+cku kpi target --agent <id> --value 25
+cku kpi rca --agent <id> --since 2026-09-01 --until 2026-09-30
+```
+
+There is **no delete** for a card — the board retires one by moving it to `rejected`, which is reversible. Only `description` is editable after creation; `cause`, fix and severity are fixed at create, so correcting one means creating a replacement.
+
+`GET /pending-tasks` returns every column including `done` and `rejected`, so a closed card is not a gone card. The list prints a **COLUMN** column for exactly that reason, and `--column` filters on it.
+
+### The dashboard credential
+
+```bash
+cku dashboard login     # separate from `cku login`; the token lasts 24h, renewed silently
+cku dashboard whoami
+cku dashboard probe     # which dashboard routes this token reaches
+```
+
+The dashboard API needs a *different* token from `/cli/*` — they're not interchangeable, and each rejects the other with an opaque 401. This also unlocks `cku analyzers` and `cku models`. The dashboard token expires every 24h with no refresh endpoint, so `cku dashboard login` saves your password (plain text, mode 0600, alongside the tokens) and re-logs in for you when it lapses. Pass `--no-save-password` to keep it off disk and re-enter it daily; `cku dashboard logout` deletes it.
+
+### Knowing which models are actually valid
+
+```bash
+cku models               # per slot, and which field each governs
+cku models --slot agent
+```
+
+Models are scoped per slot and **the slots disagree**: `agent` has 44, `post-call` has 9 and excludes `gpt-4o` and `o4-mini`. So the same value is valid in `model` and refused in `postcallmodel`. Works with or without a dashboard session, and says which source it read.
+
+### A catalogue that can't silently rot
+
+The provider tables, and now the model lists, are regenerated from the server rather than hand-copied:
+
+```bash
+npm run catalog:sync     # refresh from the bundle + the live server
+npm run catalog:check    # fail if catalog.json disagrees with the snapshot
+```
+
+`catalog:check` runs offline against a committed snapshot, so it works in CI with no credentials. On 1 October 2026 it caught shipped tables that listed withdrawn models *and* missed live ones in both directions. A wrong voice model otherwise persists silently and only surfaces as a broken call.
+
+### Smaller things
+
+- `cku calls logs` — grep/awk/sed over the raw call log, in-process, no subprocess and no shell
+- `cku accounts status` — reports which account is in effect **and where that choice came from**
+- Per-project binding, so parallel agents can't redirect each other
+- `secrets set` without the value on the command line
+- `--json` that stays unpaged for scripting, with human tables paged
+
+---
+
+## Staying current
+
+A daily workflow checks npm for a newer `@callkaro-official/cli` and, when it finds one, regenerates the provider catalogue and opens a PR onto the `official` branch. It never merges anything itself.
+
+| Branch | What's on it |
+|---|---|
+| `official` | Clean base. Changes only arrive through sync PRs. |
+| `main` | `official` plus your customizations. Your working branch. |
+
+To take an update: review the PR, merge into `official`, then merge `official` into `main`.
+
+Worth knowing what the sync does and doesn't do. It regenerates `src/data/catalog.json` — the provider tables and the per-slot LLM model lists — because those change when the dashboard changes. It does **not** port command code, because the official source isn't available, so that's maintained by hand. The PR lists which commands were added or removed so you know what to look at.
+
+Keep your customizations in as few files as you can. That diff is the one you have to resolve on every update.
+
+---
+
+## Development
+
+```bash
+npm run build          # tsc -> dist/, copy endpoints.json, chmod +x
+npm test               # build, then node --test
+npm run test:only      # tests without rebuilding
+npm run dev            # build and run
+npm run catalog:sync   # regenerate the catalogue: provider tables + per-slot LLM lists, from the server
+npm run catalog:check  # fail if catalog.json disagrees with the server snapshot (offline)
+npm run catalog:check:live  # same, against the live server (needs `cku dashboard login`)
+```
+
+Single test file:
+
+```bash
+node --test tests/agentUpdate.test.js
+```
+
+210 tests. No linter or formatter is configured.
+
+### Layout
+
+`src/index.ts` is commander wiring and almost nothing else. Every command, flag and description is declared there. `src/commands/` holds one module per command group. `src/lib/` holds the shared layer, and that's where the rules worth knowing live:
+
+- **`api.ts`** is the only place that talks to the backend. Adding an endpoint means adding a method here, not a raw `fetch` in a command.
+- **`looseJson.ts`** has two parsers, chosen by where the text came from. Values from argv get a repair pass, because PowerShell strips quotes out of single-quoted arguments and `--set '{"name":"x"}'` arrives as `{name:x}`. Values from files or stdin are parsed strictly, since the shell never touched them and a real typo should be reported rather than guessed at.
+- **`agentUpdate.ts`** merges updates into objects the backend replaces wholesale, so a partial update doesn't drop its siblings.
+- **`ui.ts`** sets `process.exitCode` rather than calling `process.exit()`. On Windows, exiting while a fetch socket is still closing trips a libuv assertion that aborts with code 127 and a pile of C-level noise.
+
+### Regenerating docs
+
+Both of these read from the code, so they can't drift:
+
+```bash
+node scripts/gen-api-inventory.js          # endpoint tables in docs/api.md
+node scripts/gen-cli-reference.js ../callkaro-skills/skills/callkaro-cli/REFERENCE.md
+```
+
+---
+
+## Skills
+
+The CLI installs a skill pack for Claude Code and other coding agents, so an agent can drive `cku` without being told how.
+
+```bash
+cku skills install --claude          # this fork's pack
+cku skills install --claude --official   # the upstream pack
+cku skills update                    # refresh every install
+```
+
+Targets include `--cursor --copilot --gemini --windsurf --roo --opencode --cline --codex --all`, plus `--project` to install into a repo rather than your user account. Skills ship from GitHub, so a new one reaches users without a CLI release.
+
+---
+
+## License
+
+Apache-2.0, matching the upstream CLI.

package/dist/commands/accounts.js

@@ -116,12 +116,15 @@ async function whoamiCommand(opts) {
         if (opts.json)
             return void console.log(JSON.stringify(res, null, 2));
         const user = res.user || res;
+        const monitoring = res.monitoring?.active ? res.monitoring.account : undefined;
         if (!user?.email) {
             (0, ui_1.fail)('Could not read your account details. Run `cku login`.');
             process.exitCode = 1;
             return;
         }
         (0, ui_1.success)(`Logged in as ${user.email}`);
+        if (monitoring)
+            (0, ui_1.info)(`  MONITORING ${monitoring.name || monitoring.email} (${monitoring.id})`);
     }
     catch (err) {
         (0, ui_1.handleError)(err);
@@ -148,6 +151,9 @@ async function configCommand() {
     else {
         (0, ui_1.info)('  session      not signed in — run `cku login`');
     }
+    const monitored = process.env.CK_ACCOUNT_ID || cfg.monitoring?.id;
+    if (monitored)
+        (0, ui_1.info)(`  monitoring   ${monitored}  (acting on a client account — \`cku monitor clear\` to leave)`);
     (0, ui_1.info)(`  accounts     ${accounts.length} saved${accounts.length ? ` — \`cku accounts list\`` : ''}`);
 }
 /** `cku accounts` — list / switch / add / remove stored logins. */

package/dist/commands/agents.js

@@ -427,9 +427,14 @@ async function agentsUpdateCommand(agentId, opts) {
         // *target* version: without one, getAgent returns the default version, and
         // its siblings (provider, voice id, …) would be written onto a different
         // version. Wholesale keys are version-level, so --versions is set here.
-        if (wholesaleKeys.length) {
+        // `functions` is a whole array on the backend: merge by name unless the
+        // caller asked to replace the list.
+        const mergeFns = Array.isArray(patch.functions) && !opts.replaceFunctions;
+        if (wholesaleKeys.length || mergeFns) {
             const { agent } = await api.getAgent(agentId, (0, versions_1.firstVersion)(opts.versions));
             patch = (0, agentUpdate_1.mergeWholesaleKeys)(patch, agent);
+            if (mergeFns)
+                patch.functions = (0, agentUpdate_1.mergeFunctions)(patch.functions, agent.functions);
         }
         // A commit message is recorded against a version. Version-level updates
         // already name one; for an agent-level-only update with --commit, attach it

package/dist/commands/monitor.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.monitorListCommand = monitorListCommand;
+exports.monitorUseCommand = monitorUseCommand;
+exports.monitorCurrentCommand = monitorCurrentCommand;
+exports.monitorClearCommand = monitorClearCommand;
+const config_1 = require("../lib/config");
+const session_1 = require("../lib/session");
+const ui_1 = require("../lib/ui");
+// Official v5 `accounts` group, renamed: `cku accounts` already means local saved logins.
+async function monitorListCommand(opts) {
+    try {
+        const api = (0, session_1.requireApi)();
+        const { accounts } = await api.listClientAccounts();
+        if (opts.json)
+            return void console.log(JSON.stringify(accounts, null, 2));
+        if (!accounts?.length)
+            return void (0, ui_1.info)('No client accounts are assigned to you.');
+        const current = (0, config_1.monitoringAccountId)();
+        (0, ui_1.table)(['Active', 'Name', 'Email', 'Account ID'], accounts.map((a) => [current === a.id ? '*' : '', a.name || '', a.email || '', a.id]));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function monitorUseCommand(accountId) {
+    try {
+        const api = (0, session_1.requireApi)();
+        const { accounts } = await api.listClientAccounts();
+        const account = (accounts || []).find((a) => a.id === accountId);
+        if (!account) {
+            (0, ui_1.fail)('That client account is not assigned to you. Run `cku monitor list`.');
+            process.exitCode = 1;
+            return;
+        }
+        if (!(0, config_1.setMonitoring)({ id: account.id, name: account.name, email: account.email })) {
+            (0, ui_1.fail)('No stored account to save this on (CK_TOKEN only?). Set CK_ACCOUNT_ID for this shell instead.');
+            process.exitCode = 1;
+            return;
+        }
+        (0, ui_1.success)(`Monitoring ${account.name || account.email || account.id}. Every command now acts on that account.`);
+        if (process.env.CK_ACCOUNT_ID)
+            (0, ui_1.info)('  CK_ACCOUNT_ID is set and overrides this; unset it to use the stored choice.');
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+function monitorCurrentCommand(opts) {
+    const envId = process.env.CK_ACCOUNT_ID;
+    const stored = (0, config_1.loadConfig)().monitoring;
+    if (!envId && !stored)
+        return void (0, ui_1.info)('Monitoring mode is off.');
+    const current = envId ? { id: envId, source: 'CK_ACCOUNT_ID' } : { ...stored, source: 'config' };
+    if (opts.json)
+        return void console.log(JSON.stringify(current, null, 2));
+    (0, ui_1.keyValue)({
+        mode: 'MONITORING',
+        account: envId || stored?.name || stored?.email || stored?.id,
+        accountId: current.id,
+        source: current.source,
+    });
+}
+function monitorClearCommand() {
+    if (process.env.CK_ACCOUNT_ID) {
+        (0, ui_1.fail)('CK_ACCOUNT_ID is set for this process. Unset it to leave monitoring mode.');
+        process.exitCode = 1;
+        return;
+    }
+    (0, config_1.setMonitoring)(undefined);
+    (0, ui_1.success)('Monitoring mode is off.');
+}

package/dist/index.js

@@ -8,6 +8,7 @@ const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const ui_1 = require("./lib/ui");
 const accounts_1 = require("./commands/accounts");
+const monitor_1 = require("./commands/monitor");
 const dashboardAuth_1 = require("./lib/dashboardAuth");
 const kpi_1 = require("./commands/kpi");
 /** Board columns, for `--help`. Ids are what the server keys on, not labels. */
@@ -281,6 +282,28 @@ accounts
     .description('forget a saved login')
     .option('--yes', 'skip confirmation')
     .action(accounts_1.accountsRemoveCommand);
+// --- monitoring mode (official 5.0: client accounts assigned to you) -------
+const monitor = program
+    .command('monitor')
+    .description('act on a client account assigned to you (official 5.0 `accounts`, renamed)');
+monitor
+    .command('list', { isDefault: true })
+    .description('list client accounts assigned to you (* = monitored)')
+    .option('--json', 'output raw JSON')
+    .action(monitor_1.monitorListCommand);
+monitor
+    .command('use <accountId>')
+    .description('enter monitoring mode: every command acts on that client account')
+    .action(monitor_1.monitorUseCommand);
+monitor
+    .command('current')
+    .description('show the monitored account, if any')
+    .option('--json', 'output raw JSON')
+    .action(monitor_1.monitorCurrentCommand);
+monitor
+    .command('clear')
+    .description('leave monitoring mode')
+    .action(monitor_1.monitorClearCommand);
 program
     .command('update')
     .description('upgrade the CLI to the latest release, then refresh the skill pack')
@@ -325,6 +348,7 @@ agents.command('update <agentId>').description('update fields via --set \'{json}
     .option('--set <json>', "JSON object of fields (or @file.json), e.g. '{\"name\":\"x\",\"temperature\":5}'")
     .option('--versions <id>', 'target a specific version (needed for version-level fields)')
     .option('--commit <msg>', 'commit message for the version change')
+    .option('--replace-functions', 'replace the whole functions list instead of merging by name (default merges; omitted functions are kept)')
     .option('--json', 'output the raw updated-agent response')
     .action(agents_1.agentsUpdateCommand);
 // Phone assignment (agent-centric). The one-inbound-agent rule is enforced server-side.

package/dist/lib/agentUpdate.js

@@ -9,6 +9,7 @@ exports.preparePatch = preparePatch;
 exports.coerce = coerce;
 exports.deepMerge = deepMerge;
 exports.mergeWholesaleKeys = mergeWholesaleKeys;
+exports.mergeFunctions = mergeFunctions;
 exports.isAgentLevelKey = isAgentLevelKey;
 exports.normalizeStringArray = normalizeStringArray;
 const agentImport_1 = require("./agentImport");
@@ -251,6 +252,35 @@ function mergeWholesaleKeys(patch, current) {
     }
     return out;
 }
+/**
+ * Merge a partial `functions` array into the version's current one, by `name`:
+ * a matching name is replaced, a new name is appended, the rest are kept.
+ *
+ * The backend replaces the whole array, so sending one function would delete
+ * every other function on the version while reporting success.
+ */
+function mergeFunctions(incoming, current) {
+    if (!Array.isArray(incoming))
+        throw new Error('"functions" must be an array of function objects.');
+    const out = Array.isArray(current) ? [...current] : [];
+    const seen = new Set();
+    incoming.forEach((fn, i) => {
+        const name = fn && typeof fn === 'object' ? fn.name : undefined;
+        if (typeof name !== 'string' || !name.trim()) {
+            throw new Error(`functions[${i}] has no "name". Functions are merged by name, so each needs one.\n` +
+                '  To replace the whole list on purpose, pass --replace-functions.');
+        }
+        if (seen.has(name))
+            throw new Error(`functions lists "${name}" twice.`);
+        seen.add(name);
+        const at = out.findIndex((c) => c && c.name === name);
+        if (at >= 0)
+            out[at] = fn;
+        else
+            out.push(fn);
+    });
+    return out;
+}
 function isAgentLevelKey(key) {
     return agentImport_1.AGENT_LEVEL_KEYS.has(key);
 }

package/dist/lib/api.js

@@ -13,21 +13,26 @@ const types_1 = require("./types");
  */
 class Api {
     token;
+    monitoringAccountId;
     baseUrl;
     callBaseUrl;
-    constructor(baseUrl, callBaseUrl, token) {
+    constructor(baseUrl, callBaseUrl, token, monitoringAccountId) {
         this.token = token;
+        this.monitoringAccountId = monitoringAccountId;
         this.baseUrl = baseUrl.replace(/\/+$/, '');
         this.callBaseUrl = (callBaseUrl || baseUrl).replace(/\/+$/, '');
     }
-    request(method, path, body) {
-        return this.requestTo(this.baseUrl, method, path, body);
+    request(method, path, body, includeAccount = true) {
+        return this.requestTo(this.baseUrl, method, path, body, includeAccount);
     }
     /** Same as request(), but against a specific base URL (e.g. the call cloud). */
-    async requestTo(base, method, path, body) {
+    async requestTo(base, method, path, body, includeAccount = true) {
         const headers = { 'Content-Type': 'application/json' };
         if (this.token)
             headers.Authorization = `Bearer ${this.token}`;
+        // Monitoring mode: every request, writes included, acts on the client account.
+        if (includeAccount && this.monitoringAccountId)
+            headers['X-CallKaro-Account-Id'] = this.monitoringAccountId;
         let res;
         try {
             res = await fetch(`${base}${path}`, {
@@ -59,6 +64,8 @@ class Api {
         return this.request('GET', `/cli/auth/browser/poll?code=${encodeURIComponent(code)}&secret=${encodeURIComponent(secret)}`);
     }
     me() { return this.request('GET', '/cli/auth/me'); }
+    /** Client accounts assigned to this user. Sent without the monitoring header: it lists, not acts. */
+    listClientAccounts() { return this.request('GET', '/cli/auth/accounts', undefined, false); }
     // --- secrets --------------------------------------------------------------
     listSecrets() { return this.request('GET', '/cli/secrets'); }
     saveSecrets(secrets) { return this.request('PUT', '/cli/secrets', { secrets }); }

package/dist/lib/config.js

@@ -27,6 +27,8 @@ exports.removeAccount = removeAccount;
 exports.loadConfig = loadConfig;
 exports.clearSession = clearSession;
 exports.saveLogin = saveLogin;
+exports.monitoringAccountId = monitoringAccountId;
+exports.setMonitoring = setMonitoring;
 exports.getClient = getClient;
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -347,8 +349,21 @@ function saveLogin(email, session) {
         ? saved + `  This shell still uses ${current} via CK_ACCOUNT. Unset it, or set CK_ACCOUNT=${email}, to switch.`
         : saved + `  This folder still uses ${current} via .cku.json. Run \`cku accounts bind ${email}\` to switch.`;
 }
+/** The client account in effect, if any: CK_ACCOUNT_ID wins over the stored choice. */
+function monitoringAccountId(cfg = loadConfig()) {
+    return process.env.CK_ACCOUNT_ID || cfg.monitoring?.id || undefined;
+}
+/** Set or clear (undefined) the monitored account on the effective stored account. */
+function setMonitoring(monitoring) {
+    const slug = activeAccount();
+    if (!slug || !(0, fs_1.existsSync)(accountPath(slug)))
+        return false;
+    const { monitoring: _old, ...rest } = loadAccount(slug);
+    writeJson(accountPath(slug), monitoring ? { ...rest, monitoring } : rest);
+    return true;
+}
 /** Build the API client from the endpoint URLs + resolved token. */
 function getClient() {
     const cfg = loadConfig();
-    return { api: new api_1.Api(backendUrl(), callUrl(), cfg.token), cfg };
+    return { api: new api_1.Api(backendUrl(), callUrl(), cfg.token, monitoringAccountId(cfg)), cfg };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "callkaro-cli-unofficial",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "description": "Unofficial fork of the CallKaro CLI — manage your voice AI agents from the terminal",
   "bin": {