callkaro-cli-unofficial 0.2.1 → 0.4.0

package/README.md

@@ -1,260 +1,264 @@
-# 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 agents chat` — text chat with an agent's real prompt and tools, no phone call. Scriptable with `--say`, replayable with `--history`. Custom in-call functions run for real
+- `cku scheduled list|queued|get` — scheduled calls and the queue of what will actually dial (dashboard login)
+- `cku sim update` — edit a test case in place
+- `cku calls list --postcall dnc_requested=true --provider-type plivo --sid <sid>` — filters the official CLI doesn't expose
+- `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
+```
+
+269 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/agentChat.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentChatCommand = agentChatCommand;
+const fs_1 = require("fs");
+const prompts_1 = __importDefault(require("prompts"));
+const chalk_1 = __importDefault(require("chalk"));
+const session_1 = require("../lib/session");
+const ui_1 = require("../lib/ui");
+const versions_1 = require("../lib/versions");
+const types_1 = require("../lib/types");
+const jsonInput_1 = require("./jsonInput");
+/**
+ * Text-only conversation with an agent over POST /cli/simulations/generate-reply.
+ * One request per user turn: the server replays the whole history through the
+ * agent's real prompt and tools and returns the next agent turn. No call, no
+ * telephony spend.
+ *
+ * Tools: the Python side mocks end_call, transfer_call, warm_transfer,
+ * keep_call_on_hold, change_conversation_language, send_booking_link_to_whatsapp,
+ * use_knowledge_base and collect_digits_via_dtmf. Every other function RUNS FOR
+ * REAL (and falls back to a mock if it throws) — a CRM write in an in-call
+ * function really happens.
+ */
+const MOCKED_TOOLS = new Set([
+    'end_call', 'transfer_call', 'warm_transfer', 'keep_call_on_hold',
+    'change_conversation_language', 'send_booking_link_to_whatsapp',
+    'use_knowledge_base', 'collect_digits_via_dtmf',
+]);
+/** Agent text of a message item; the server returns `content` as an array of strings. */
+const text = (item) => Array.isArray(item.content) ? item.content.join(' ') : String(item.content ?? '');
+const isEnd = (items) => items.some((i) => i.type === 'function_call' && i.name === 'end_call');
+/** Turn the server's error for a bad version or history into one that names the fix. */
+function explain(err, versionId) {
+    if (!(err instanceof types_1.ApiError))
+        return err;
+    if (err.status === 502 && /Invalid version id|Agent version not found/i.test(err.message)) {
+        return new Error(`Version ${versionId} is not a version of this agent. List them with: cku agents versions <agentId>`);
+    }
+    if (err.status === 400 && /must end with a user message/i.test(err.message)) {
+        return new Error('The chat history must end with a user turn. Add one with --say "<text>".');
+    }
+    return err;
+}
+function printItems(items, warned) {
+    for (const item of items) {
+        if (item.type === 'message' && item.role === 'assistant') {
+            (0, ui_1.info)(`${chalk_1.default.cyan('agent>')} ${text(item)}`);
+        }
+        else if (item.type === 'function_call') {
+            const result = JSON.stringify(item.extra?.result ?? null);
+            (0, ui_1.info)(chalk_1.default.dim(`  → ${item.name} ${item.arguments || '{}'} = ${result}`));
+            if (!MOCKED_TOOLS.has(item.name) && !warned.has(item.name)) {
+                warned.add(item.name);
+                console.error(chalk_1.default.yellow(`  ! ${item.name} is not mocked: it ran for real.`));
+            }
+        }
+    }
+}
+async function buildMetadata(opts) {
+    const metadata = {};
+    if (opts.metadata) {
+        const parsed = await (0, jsonInput_1.readJsonFlag)(opts.metadata, '--metadata');
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('--metadata must be a JSON object, e.g. {"customer_name":"Ravi"}');
+        }
+        Object.assign(metadata, parsed);
+    }
+    for (const pair of opts.var || []) {
+        const idx = pair.indexOf('=');
+        if (idx < 1)
+            throw new Error(`Bad --var "${pair}". Use key=value, e.g. --var customer_name=Ravi`);
+        metadata[pair.slice(0, idx)] = pair.slice(idx + 1);
+    }
+    return metadata;
+}
+async function agentChatCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const versionId = (0, versions_1.firstVersion)(opts.versions);
+        const metadata = await buildMetadata(opts);
+        let history = [];
+        if (opts.history) {
+            const parsed = await (0, jsonInput_1.readJsonFlag)(opts.history, '--history');
+            if (!Array.isArray(parsed))
+                throw new Error('--history must be a JSON array of chat items (the output of --json).');
+            history = parsed;
+        }
+        const scripted = (opts.say?.length ?? 0) > 0 || Boolean(opts.history);
+        if (!scripted)
+            (0, ui_1.needTty)('Pass --say "<text>" (repeatable) or --history @file.json to run without a terminal.');
+        // Python requires userId in the body; take it from the token's own account.
+        const me = await api.me();
+        const userId = me.user?.id;
+        if (!userId)
+            throw new Error('Could not read your account id from /cli/auth/me.');
+        const warned = new Set();
+        let promptShown = false;
+        let ended = false;
+        const turn = async () => {
+            const res = await api
+                .generateReply({ userId, agent_id: agentId, chat_history: history, configuration: {}, epoch: 1, metadata }, versionId)
+                .catch((e) => { throw explain(e, versionId); });
+            if (opts.showPrompt && !promptShown) {
+                promptShown = true;
+                const sys = (res.messages || []).find((m) => m.role === 'system');
+                if (sys)
+                    (0, ui_1.info)(chalk_1.default.dim(`--- system prompt ---\n${sys.content}\n---------------------`));
+            }
+            const items = res.replies?.[0] || [];
+            history.push(...items);
+            if (!opts.json)
+                printItems(items, warned);
+            ended = isEnd(items);
+        };
+        const userSays = async (line) => {
+            history.push({ type: 'message', role: 'user', content: line });
+            if (!opts.json)
+                (0, ui_1.info)(`${chalk_1.default.green('you>')} ${line}`);
+            await turn();
+        };
+        // A replayed history may already end on a user turn waiting for its reply.
+        if (history.length && history[history.length - 1].role === 'user')
+            await turn();
+        if (scripted) {
+            for (const line of opts.say || []) {
+                if (ended)
+                    break;
+                await userSays(line);
+            }
+        }
+        else {
+            (0, ui_1.info)(chalk_1.default.dim('Text chat with the agent. /reset, /save <file>, /exit. Ends after end_call.'));
+            while (!ended) {
+                const { line } = await (0, prompts_1.default)({ type: 'text', name: 'line', message: 'you' });
+                if (line === undefined || line === '/exit')
+                    break;
+                const cmd = String(line).trim();
+                if (!cmd)
+                    continue;
+                if (cmd === '/reset') {
+                    history = [];
+                    (0, ui_1.info)(chalk_1.default.dim('History cleared.'));
+                    continue;
+                }
+                if (cmd.startsWith('/save ')) {
+                    (0, fs_1.writeFileSync)(cmd.slice(6).trim(), JSON.stringify(history, null, 2));
+                    (0, ui_1.info)(chalk_1.default.dim(`Saved ${history.length} items.`));
+                    continue;
+                }
+                await userSays(cmd);
+            }
+        }
+        if (ended && !opts.json)
+            (0, ui_1.info)(chalk_1.default.dim('(agent ended the call)'));
+        if (opts.save)
+            (0, fs_1.writeFileSync)(opts.save, JSON.stringify(history, null, 2));
+        if (opts.json)
+            console.log(JSON.stringify(history, null, 2));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}

package/dist/commands/calls.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.postcallQuery = postcallQuery;
 exports.buildCallQuery = buildCallQuery;
 exports.callsListCommand = callsListCommand;
 exports.callsGetCommand = callsGetCommand;
@@ -17,6 +18,24 @@ function fmtTime(v) {
     const d = new Date(v);
     return isNaN(d.getTime()) ? '' : d.toLocaleString('en-US');
 }
+/**
+ * `--postcall name=true|false` → `postcall_name=true|false`. The server only matches
+ * the literal strings `true`/`false` and silently drops any other value, which would
+ * return every call — so anything else is rejected here.
+ */
+function postcallQuery(pairs = []) {
+    const out = {};
+    for (const pair of pairs) {
+        const m = /^([^=\s]+)=(true|false)$/.exec(pair.trim());
+        if (!m) {
+            throw new Error(`Invalid --postcall "${pair}". Use --postcall <variable>=true or <variable>=false ` +
+                `(boolean post-call variables only; the server ignores any other value). ` +
+                `Example: --postcall dnc_requested=true`);
+        }
+        out[`postcall_${m[1]}`] = m[2];
+    }
+    return out;
+}
 function buildCallQuery(o) {
     return {
         name: o.type,
@@ -31,6 +50,9 @@ function buildCallQuery(o) {
         conversion_status: o.converted,
         lead_id: o.lead,
         buylead: o.buylead,
+        provider_type: o.providerType,
+        call_sid: o.sid,
+        ...postcallQuery(o.postcall),
     };
 }
 async function callsListCommand(opts) {

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/commands/scheduled.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduledListCommand = scheduledListCommand;
+exports.scheduledQueuedCommand = scheduledQueuedCommand;
+exports.scheduledGetCommand = scheduledGetCommand;
+const dashboardApi_1 = require("../lib/dashboardApi");
+const ui_1 = require("../lib/ui");
+/**
+ * Scheduled calls, read-only. `/schedulecalls/v1/*` takes the dashboard cookie,
+ * so these need `cku dashboard login`; the `/cli` tree has no scheduled-call
+ * routes and the `/mcp` ones reject the ck_ token.
+ *
+ * No cancel: the backend's single-call delete removes the job and books a new
+ * attempt instead, and neither delete checks ownership of the job id.
+ */
+const when = (v) => {
+    if (v === undefined || v === null || v === '')
+        return '';
+    const d = new Date(v);
+    return isNaN(d.getTime()) ? String(v) : d.toLocaleString('en-US');
+};
+const agentName = (a) => (a && typeof a === 'object' ? a.name || a._id : a) || '';
+async function scheduledListCommand(opts) {
+    try {
+        const page = (0, ui_1.intFlag)(opts.page, '--page', 1);
+        const pageSize = (0, ui_1.intFlag)(opts.limit, '--limit', 50);
+        const res = await (0, dashboardApi_1.dashboardApi)().scheduledCalls({ page, pageSize });
+        const rows = res?.scheduleCalls || [];
+        if (opts.json)
+            return void console.log(JSON.stringify(rows, null, 2));
+        if (!rows.length)
+            return void (0, ui_1.info)('No scheduled calls.');
+        (0, ui_1.table)(['ID', 'TO', 'AGENT', 'SCHEDULED FOR', 'RETRIES', 'BATCH'], rows.map((r) => [r._id, r.to_number, agentName(r.agent_id), r.schedule_at, r.number_of_retries ?? '', r.batch_id || '']));
+        const p = res.pagination || {};
+        (0, ui_1.info)(`Page ${p.page ?? page} of ${p.totalPages ?? '?'} (${p.totalDocs ?? rows.length} total). Created today: ${res.todaysCalls ?? 0}.`);
+        if (p.hasNext)
+            (0, ui_1.info)(`Next: cku scheduled list --page ${(p.page ?? page) + 1}`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function scheduledQueuedCommand(opts) {
+    try {
+        const res = await (0, dashboardApi_1.dashboardApi)().queuedScheduledCalls();
+        const jobs = res?.scheduleCalls || [];
+        if (opts.json)
+            return void console.log(JSON.stringify(jobs, null, 2));
+        if (!jobs.length)
+            return void (0, ui_1.info)('Nothing queued: no scheduled call is waiting to dial.');
+        // The queue returns jobs in no useful order; soonest first.
+        const due = (j) => (j.timestamp || 0) + (j.delay || 0);
+        jobs.sort((a, b) => due(a) - due(b));
+        (0, ui_1.table)(['JOB ID', 'TO', 'AGENT ID', 'DIALS AT', 'TRY', 'FOLLOW-UP'], jobs.map((j) => [
+            j.id, j.data?.to_number, j.data?.agent_id, when(due(j)),
+            j.data?.try_count ?? '', j.data?.follow_up_call ? 'yes' : '',
+        ]));
+        (0, ui_1.info)(`${jobs.length} queued.`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function scheduledGetCommand(id, opts) {
+    try {
+        const res = await (0, dashboardApi_1.dashboardApi)().scheduledCall(id);
+        if (opts.json)
+            return void console.log(JSON.stringify(res, null, 2));
+        const s = res.scheduleCall || {};
+        (0, ui_1.keyValue)({
+            ID: s._id,
+            To: s.to_number,
+            Agent: agentName(s.agent_id),
+            'Scheduled for': s.schedule_at,
+            Language: s.call_language,
+            Retries: s.number_of_retries,
+            'Retry gaps (min)': (s.gap_between_retries || []).join(', '),
+            Window: s.min_trigger_time && `${s.min_trigger_time}–${s.max_trigger_time}`,
+            Batch: s.batch_id || '',
+            Metadata: s.metadata ? JSON.stringify(s.metadata) : '',
+            'Still queued': (res.futureCalls || []).length ? 'yes' : 'no',
+        });
+        const done = res.completedCalls || [];
+        if (done.length) {
+            (0, ui_1.info)('');
+            (0, ui_1.table)(['CALL ID', 'TRY', 'HANGUP', 'DURATION', 'WHEN'], done.map((c) => [c._id, c.try_count ?? '', c.hangup_reason || '', c.call_duration ?? '', when(c.createdAt)]));
+        }
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}

package/dist/commands/simulations.js

@@ -8,6 +8,7 @@ exports.toTestVariables = toTestVariables;
 exports.toTestFunctions = toTestFunctions;
 exports.simTestsListCommand = simTestsListCommand;
 exports.simCreateCommand = simCreateCommand;
+exports.simUpdateCommand = simUpdateCommand;
 exports.simDeleteCommand = simDeleteCommand;
 exports.waitForBatch = waitForBatch;
 exports.simRunCommand = simRunCommand;
@@ -95,6 +96,37 @@ async function simCreateCommand(agentId, opts) {
         (0, ui_1.handleError)(err);
     }
 }
+/**
+ * Edit a test case. Sends only the fields given: the server passes the body to
+ * findByIdAndUpdate as-is, so anything else in it (userId, agentId) would be written.
+ * --variables / --functions replace the whole map / list, they do not merge.
+ */
+async function simUpdateCommand(testCaseId, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const body = {};
+        if (opts.name !== undefined)
+            body.testcaseName = opts.name;
+        if (opts.prompt !== undefined)
+            body.userPrompt = opts.prompt;
+        if (opts.criteria !== undefined)
+            body.successCriteria = opts.criteria;
+        if (opts.model !== undefined)
+            body.testLLMModel = opts.model;
+        if (opts.variables !== undefined)
+            body.testVariables = toTestVariables(await (0, jsonInput_1.readJsonFlag)(opts.variables, '--variables'));
+        if (opts.functions !== undefined)
+            body.testFunctions = toTestFunctions(await (0, jsonInput_1.readJsonFlag)(opts.functions, '--functions'));
+        if (!Object.keys(body).length) {
+            return (0, ui_1.handleError)(new Error('Nothing to update. Pass at least one of --name, --prompt, --criteria, --model, --variables, --functions.'));
+        }
+        const res = await api.updateTestCase(testCaseId, body);
+        (0, ui_1.success)(`Updated test case ${res.testCase?._id || testCaseId}: ${Object.keys(body).join(', ')}.`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
 async function simDeleteCommand(testCaseId, opts) {
     const api = (0, session_1.requireApi)();
     try {

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. */
@@ -15,6 +16,8 @@ const KPI_COLUMNS = 'action_items | in_progress | testing_ab | live_prod | done
 const analyzers_1 = require("./commands/analyzers");
 const models_1 = require("./commands/models");
 const agents_1 = require("./commands/agents");
+const agentChat_1 = require("./commands/agentChat");
+const scheduled_1 = require("./commands/scheduled");
 const agentVersions_1 = require("./commands/agentVersions");
 const agentPhone_1 = require("./commands/agentPhone");
 const whatsapp_1 = require("./commands/whatsapp");
@@ -39,6 +42,11 @@ const chatAgents_1 = require("./commands/chatAgents");
 // last silently wins. `cku` cannot collide.
 const name = 'cku';
 const { version: VERSION } = require('../package.json');
+/** Collect repeatable flag values (--var, --say, --postcall) into an array. */
+const collectVar = (val, acc) => {
+    acc.push(val);
+    return acc;
+};
 const program = new commander_1.Command();
 program
     .name(name)
@@ -281,6 +289,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')
@@ -307,6 +337,27 @@ agents.command('get <agentId>').description('show one agent and list its version
     .option('--json', 'output raw JSON')
     .option('--file <path>', 'save the agent detail as JSON to a file')
     .action(agents_1.agentsGetCommand);
+agents.command('chat <agentId>')
+    .description('text-chat with an agent, no phone call (custom in-call functions RUN FOR REAL)')
+    .option('--versions <id>', 'version to talk to (default: the published one)')
+    .option('--metadata <json|@file>', 'call metadata as a JSON object')
+    .option('--var <k=v>', 'call metadata variable (repeatable)', collectVar, [])
+    .option('--say <text>', 'user turn, repeatable, run in order; no terminal needed', collectVar, [])
+    .option('--history <json|@file>', 'replay a saved conversation (the output of --json) before --say')
+    .option('--save <file>', 'write the conversation to a file at the end (readable by --history)')
+    .option('--show-prompt', 'print the rendered system prompt once (checks metadata substitution)')
+    .option('--json', 'print only the final conversation as JSON')
+    .addHelpText('after', `
+Not mocked: any custom in-call function. It really runs (CRM write, webhook, WhatsApp).
+Mocked: end_call, transfer_call, warm_transfer, keep_call_on_hold, use_knowledge_base,
+  change_conversation_language, send_booking_link_to_whatsapp, collect_digits_via_dtmf.
+
+Examples:
+  cku agents chat <agentId>
+  cku agents chat <agentId> --var customer_name=Ravi --say "Hello?" --say "Not interested"
+  cku agents chat <agentId> --say "hi" --json > convo.json
+  cku agents chat <agentId> --history @convo.json --say "What was that again?"`)
+    .action(agentChat_1.agentChatCommand);
 agents.command('versions <agentId>').description("list an agent's versions (name, id, language, prompt type, active)")
     .option('--json', 'output raw JSON')
     .option('--file <path>', 'save the version list as JSON to a file')
@@ -471,13 +522,11 @@ function addCallFilters(cmd) {
         .option('--to <number>', 'destination number')
         .option('--converted <bool>', 'conversion status: true|false')
         .option('--lead <id>', 'lead id')
-        .option('--buylead <value>', 'buylead value');
+        .option('--buylead <value>', 'buylead value')
+        .option('--postcall <name=bool>', 'boolean post-call variable, repeatable: dnc_requested=true', collectVar, [])
+        .option('--provider-type <list>', 'telephony provider(s), comma-separated: plivo,vobiz,...')
+        .option('--sid <callSid>', 'provider call SID (ignores the date window)');
 }
-/** Collect repeatable --var key=value into an array. */
-const collectVar = (val, acc) => {
-    acc.push(val);
-    return acc;
-};
 // --- voices / transcribers -------------------------------------------------
 program
     .command('voices')
@@ -520,6 +569,20 @@ program
     .option('--all', 'include admin-gated providers')
     .option('--json', 'raw JSON')
     .action(transcribers_1.transcribersCommand);
+// --- scheduled calls (dashboard cookie) -------------------------------------
+const scheduled = program.command('scheduled')
+    .description('scheduled calls, read-only (needs `cku dashboard login`)');
+scheduled.command('list').description('schedule records, newest first')
+    .option('--page <n>', 'page number (default 1)')
+    .option('--limit <n>', 'page size (default 50)')
+    .option('--json', 'raw JSON (a bare array)')
+    .action(scheduled_1.scheduledListCommand);
+scheduled.command('queued').description('jobs waiting in the queue: what will actually dial, soonest first')
+    .option('--json', 'raw JSON (a bare array of queue jobs)')
+    .action(scheduled_1.scheduledQueuedCommand);
+scheduled.command('get <id>').description('one schedule record, its completed tries, and whether it is still queued')
+    .option('--json', 'raw JSON')
+    .action(scheduled_1.scheduledGetCommand);
 // --- calls -----------------------------------------------------------------
 const calls = program.command('calls').description('calls: place & history');
 calls.command('make').description('place a single outbound call (real, or --test)')
@@ -633,6 +696,14 @@ sim.command('create <agentId>').description('create a test case')
     .option('--variables <json|@file>', 'testVariables: a JSON object of name -> value (non-strings are stringified)')
     .option('--functions <json|@file>', 'function mocks: a JSON array of {"name": ..., "response": ...}')
     .action(simulations_1.simCreateCommand);
+sim.command('update <testCaseId>').description('edit a test case (only the fields you pass are sent)')
+    .option('--name <name>', 'test case name')
+    .option('--prompt <text>', 'simulated user prompt')
+    .option('--criteria <text>', 'success criteria')
+    .option('--model <model>', 'test LLM model')
+    .option('--variables <json|@file>', 'testVariables: replaces the whole map')
+    .option('--functions <json|@file>', 'function mocks: replaces the whole list')
+    .action(simulations_1.simUpdateCommand);
 sim.command('delete <testCaseId>').description('delete a test case').option('--yes', 'skip confirmation')
     .action(simulations_1.simDeleteCommand);
 sim.command('run <agentId>').description('run a batch simulation (async)')

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 }); }
@@ -243,6 +250,11 @@ class Api {
     listTestCases(agentId) {
         return this.request('GET', `/cli/simulations/test-cases${qs({ agentId })}`);
     }
+    /** One agent turn from a chat history, no telephony (`agents chat`). */
+    generateReply(body, versionId) {
+        const q = versionId ? `?version=${encodeURIComponent(versionId)}` : '';
+        return this.request('POST', `/cli/simulations/generate-reply${q}`, body);
+    }
     updateTestCase(id, body) { return this.request('PUT', `/cli/simulations/test-cases/${id}`, body); }
     deleteTestCase(id) { return this.request('DELETE', `/cli/simulations/test-cases/${id}`); }
     runSimulation(body) { return this.request('POST', '/cli/simulations/runs', body); }

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/dist/lib/dashboardApi.js

@@ -144,6 +144,22 @@ class DashboardApi {
     deleteTestVariableSet(id) {
         return this.request('DELETE', `/v1/call-metadata-test-variables/${encodeURIComponent(id)}`);
     }
+    // --- scheduled calls (read-only) -------------------------------------------
+    // The delete routes under /schedulecalls/v1 are deliberately not wrapped: the
+    // single-call one re-schedules a new attempt rather than cancelling, and neither
+    // checks that the job belongs to the caller. See docs/plan-unused-routes.md.
+    /** Schedule records, newest first. 44k rows on a busy account: always paged. */
+    scheduledCalls(query = {}) {
+        return this.request('GET', `/schedulecalls/v1/all${qs(query)}`);
+    }
+    /** Pending jobs in the queue: what will actually dial, with `data.schedule_at`. */
+    queuedScheduledCalls() {
+        return this.request('GET', '/schedulecalls/v1/queued-scheduled-calls/all');
+    }
+    /** One schedule record plus the calls it produced and any pending job. */
+    scheduledCall(id) {
+        return this.request('GET', `/schedulecalls/v1/${encodeURIComponent(id)}`);
+    }
     // --- KPI board writes -----------------------------------------------------
     //
     // Routes, bodies and the column set below were read out of the dashboard's own

package/package.json

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