kenso 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kenso",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "The Kenso CLI: bulk lead, CRM and Studio work for people and coding agents",
   "license": "MIT",
   "type": "module",
@@ -44,5 +44,5 @@
     "typescript-eslint": "8.71.1",
     "vitest": "5.0.3"
   },
-  "gitHead": "e3f99f0ad804362414f0a972e0b352fbae1a0f27"
+  "gitHead": "17d0c13aa63ee64e49baaa76ee99cc3246d045a1"
 }

package/skill/kenso-cli/SKILL.md

@@ -1,141 +1,26 @@
 ---
 name: kenso-cli
-description: Use the Kenso CLI (kenso) for bulk lead, CRM and Studio work in a Kenso workspace from files - import, update, remove, pause or tag leads in campaigns, import accounts and people, fill Studio templates, or call any Kenso API operation from the shell. Prefer it over the Kenso MCP for anything over about 50 records.
+description: The Kenso CLI (kenso) for work from a file or over about 50 records - import, update, remove, pause, tag or export leads, import CRM accounts and people, edit Studio templates as local files and fill them, run an API operation per file row. For one record or a question, use the Kenso MCP.
 ---
 
-# Kenso CLI
-
-`kenso` does bulk work in Kenso from files and prints JSON. Use it instead of the Kenso MCP when the work starts from a file or touches more than about 50 records: the rows stay on disk, and you read a short summary.
-
-## Install and auth
-
-```bash
-npm i -g kenso
-kenso doctor
-```
-
-Needs Node 22+. Auth, in order of precedence:
-
-- `KENSO_API_KEY` in the environment (plus `KENSO_WORKSPACE_ID` when the key reaches several workspaces). Nothing else to do.
-- Or a saved key. The key is never a flag value; pipe it in. The person creates it in app.ken.so at Settings > Integrations > API keys.
-
-```bash
-echo $KEY | kenso auth login --with-key
-kenso workspace list --q acme
-kenso workspace use 1234
-kenso auth status
-```
-
-Never print, echo to the conversation, or write the key into a file in the repo. `kenso auth login` alone is browser login: it may answer `browser_login_unavailable`; then use `--with-key`. If it works, it prints a link: ask the person to open it.
-
-## Golden rules
-
-1. **stdout is data, stderr is everything else.** Piped output is JSON: one object, NDJSON for lists, one JSON summary for a batch. Errors are one JSON line on stderr: `{"error":{"code","message","field","hint","next","httpStatus","requestId"}}`.
-2. **Plan, then apply.** A batch command (import, update, remove, tag, `--each`) only plans without `--yes`: run it with `--dry-run`, read the plan, then run the exact command in its `next` (the same command with `--yes`). Never pass both. A single `kenso <resource> <action>` write and `kenso api` send at once: run it with `--dry-run` to see the request, then without it.
-3. **Pass files, not rows.** Never paste a CSV or a list of records into the conversation or a command line. Write a file and pass `--file path` (or `--ids path`).
-4. **Read the summary, then failures only.** If `failed`, `notFound` and `invalid` are 0, you are done. Otherwise read only the problem rows: `grep -E '^[0-9]+,(failed|not_found|invalid),' <results> | head -50`, or `invalidRows`. Do not read the whole results file.
-5. **Follow `next`.** An error with a known fix carries the exact command to run in `next`, and what to change in `hint`.
-6. **Branch on the exit code:**
-
-| Exit | Meaning | Do |
-|---|---|---|
-| 0 | OK (skipped rows are not failures) | Report the summary |
-| 1 | Unexpected error | Rerun with `--verbose`, report |
-| 2 | Usage or validation error | Fix the flags or the file (see `field`, `hint`) |
-| 3 | No key, bad key, or 401/403 | Ask for a key or a permission; do not retry |
-| 4 | Not found | Check the id |
-| 5 | Some rows failed, not found or invalid | Read the failed rows only, fix, resend those |
-| 6 | Rate limited, or a lead limit (`limit_reached`) stopped the run | Wait, or ask the person to raise the limit, then rerun |
-| 7 | Conflict, or another process holds the run | Read `message`; run a `next` with `--force` only after the person agrees |
-| 8 | Server error after retries | Wait a minute, rerun the same command |
-| 130 | Interrupted | Run the `next`: `kenso runs resume <runId>` |
-
-## Leads: import
-
-```bash
-kenso contacts import --template
-kenso contacts import --campaign 812 --file leads.csv --dry-run
-kenso contacts import --campaign 812 --file leads.csv --yes
-```
-
-- CSV with a header row, or JSONL. Known columns: `email`, `firstName`, `lastName`, `title`, `linkedInUrl`, `companyName`, `companyDomain` (common header spellings are matched). Every other column becomes a custom variable in snake_case (`Pain Point` fills `{{pain_point}}`).
-- Rename or drop columns: `--map '{"Pain": "customVariables.pain_point", "Notes": null}'`.
-- Blank cells are never sent; the literal `null` clears a custom variable.
-- The dry run checks every row locally (`invalid_email`, `missing_first_name`, `duplicate_in_file` ...), shows the column `mapping` and the credit estimate. Check the mapping before you apply.
-- Row statuses: `created`, `updated`, `skipped` (with `reason`: `duplicate`, `blocklisted`, `already_contacted` ...), `failed`, `invalid`. `notSendable` counts saved leads that cannot be emailed yet.
-- Up to 100,000 rows without per-row results: add `--server-import`.
-
-## Leads: update and cleanup
-
-```bash
-kenso contacts update --file edits.csv --match id --dry-run
-kenso contacts update --file edits.csv --match email --campaign 812 --yes
-kenso contacts remove --ids ids.txt --dry-run
-kenso contacts remove --where '{"campaignIds": [812], "q": "acme"}' --yes
-kenso contacts restore --run r_ab3dxk2q --yes
-kenso contacts pause --ids ids.txt --yes
-kenso contacts resume --ids ids.txt --yes
-kenso contacts tag --tag 31 --ids ids.txt --yes
-kenso contacts export --campaign 812 --out contacts.csv
-```
-
-- `update`: match by an `id`/`contactId` column, or by email within `--campaign`. A missing column or blank cell leaves a field unchanged; `null` clears it.
-- `--ids` takes one id per line, or a CSV/JSONL with an `id` column, or `-` for stdin. Get ids with `kenso contacts list --campaign-id 812 --all -o ids > ids.txt`.
-- Removing more than 1,000 needs `--confirm <count>` (the dry run's `next` has it). The remove summary has `undo`: keep it.
-
-## Runs and resume
-
-Every batch run has an id (`r_...`) and a folder with `results.csv` (one line per input row: `row,status,id,reason,error`), `invalid.csv`, `plan.json` and `run.json`. The summary prints their absolute paths.
-
-- Rerunning the same command on the same file continues an unfinished run (`"resumed":true`) or, when every row already succeeded, answers `"changed":0` and sends no writes. Writes match existing records, so a resend never duplicates.
-- `kenso runs list`, `kenso runs show <runId>`, `kenso runs resume <runId>`.
-- `--concurrency` (1-16, default 4) works on `contacts update`, `remove`, `restore`, `pause`, `resume`, `tag`, `untag`, `people import`, `accounts import` and `--each`. `contacts import` sends one chunk at a time per campaign and has no such flag. 429s and transient 5xx are retried for you. Do not add your own retry loop.
-
-## CRM and Studio (beta)
-
-Need the `accounts` or `studio` flag. Same plan-then-apply rules.
-
-```bash
-kenso accounts import --file accounts.csv --dry-run
-kenso people import --file people.csv --dry-run
-kenso studio pull 12 --dir ./tpl
-kenso studio push 12 --dir ./tpl
-kenso studio fill 12 --accounts ids.txt
-```
-
-`accounts import` charges research per created account: show the person the estimate first. `studio fill` charges per page and refuses to rerun a fill of the same file with the same flags (exit 7), but the same ids in another file are charged again. Read `kenso docs crm` and `kenso docs studio` before using them.
-
-## Workflows in plain steps (beta)
-
-Needs the `workflows` and `workflows_plain` flags. Your own model writes the workflow from the person's words, in plain steps or as custom JSON/code; Kenso only runs it, so writing costs no Kenso AI credits.
-
-```bash
-kenso workflows brief > brief.json
-kenso workflows brief --types ai.qualify@1,logic.filter@1 --include stepTypes
-kenso workflows create --data @create.json --dry-run
-kenso workflows validate --workflow-id 42
-kenso workflow-builder test --workflow-id 42 --data @test.json
-kenso workflows publish --workflow-id 42
-```
-
-- Start with `brief`: `authoring` (how plain steps become engine steps), `stepTypes`, `triggers`, `examples` and `workspace` (campaigns, Slack, secret names). `--workflow-id` returns the current definition to change; save it with `kenso workflows update --workflow-id 42 --data @update.json` and its `baseVersion`.
-- `create.json` is `{"definition": {...}}`, the definition with its `plain` block. Fix every issue `validate` names, test on one record (`{"record": {"type": "person", "id": 123}}`), then publish.
-- Never write a secret's value into a definition or the conversation: reference `{{secrets.NAME}}` and ask the person to add it in app.ken.so at Settings > Integrations > Secrets.
-
-## Everything else
-
-Every API operation is a command: `kenso <resource> <action>` (`kenso campaigns list`, `kenso tags create --name VIP`). A write like that runs at once, without `--yes`: check it with `--dry-run` first. Look commands up instead of guessing flags:
+1. Every write runs first with `--dry-run`, never `--yes`; apply with the plan's `next`. `--yes` at once only to continue an interrupted run or apply what the person confirmed.
+2. Many rows are one command with the file as it is (`--file`, `--ids`, `--each`), never a command per row. Run kenso only: no python, awk or shell tests, not even on a file or variable.
+3. Errors are JSON on stderr: follow `next`. `--force` only with the person's OK.
+4. Ids are flags: `--campaign 812` on contacts import, update, export; `--campaign-id 812` on API commands (`contacts list`). `--workspace <id>`; by name `kenso workspace list --q acme`.
 
 ```bash
-kenso describe
-kenso describe campaigns
-kenso describe campaigns update
-kenso campaigns update --help
+kenso contacts import --campaign 812 --file leads.csv --dry-run   # skips leads already in; --map '{"Pain": "customVariables.pain_point", "Notes": null}'; over 200 MB --server-import
+kenso contacts update --file edits.csv --match id --dry-run   # also one contact; or --match email --campaign 812
+kenso contacts remove --ids ids.txt --dry-run   # same for pause, resume, restore, tag --tag 31; over 1,000 add --confirm <count>
+kenso contacts remove --where '{"campaignIds": [812], "q": "acme"}' --dry-run   # also pause, resume; the plan shows the matches: no search first
+kenso contacts list --campaign-id 812 --all -o ids > ids.txt   # tag and restore take --ids only: list the ids first
+kenso contacts export --campaign 812 --out leads.csv   # a segment: kenso contact-exports create --segment-id 55
+kenso runs list   # an interrupted run (terminal lost): find it, then kenso runs resume <runId>. A changed file is a new run
+kenso accounts import --file accounts.csv --dry-run   # companies; people (any file of people) go in with kenso people import --file people.csv
+kenso studio push 12 --dir ./tpl   # to preview local edits push first (draft only; live needs --publish), then studio preview 12
+kenso studio fill 12 --accounts ids.txt --dry-run   # or --campaign 10546 --contacts leads.csv
+kenso campaigns update --campaign-id 812 --name Q4 --dry-run   # any API operation; --each rows.csv for many
+kenso mcp call list_skills
 ```
 
-- Lists print one page; `--all` streams every page, `--limit` and `--cursor` page by hand. `--fields a,b` and `--query '<JMESPath>'` shape output without `jq`.
-- Many records: `--each file.csv` runs a generated command once per row (row keys are flag or API names), with results and resume. It needs `--yes` or `--dry-run` unless it is a GET.
-- Beta commands are hidden from help until the workspace has the flag; `--all-commands` shows them.
-- Raw route: `kenso api GET /v1/me`, `kenso api POST /v1/tags --data @tag.json`. Writes through `kenso api` run without `--yes`, so be sure first.
-- MCP-only tools (such as skills): `kenso mcp tools`, `kenso mcp call skills --operation list`.
-- Offline docs: `kenso docs`, `kenso docs leads`.
+`accounts import` charges per new account, `studio fill` per page (again for the same ids in another file): show the estimate first. `pinned_by_user`: with the person's OK, `--overwrite-pinned`. Workflows: `kenso workflows brief` first; secrets only as `{{secrets.NAME}}`. Key: `KENSO_API_KEY`, or any variable piped as the first command, no check or printenv (an empty key is refused): `printf '%s' "$KEY" | kenso auth login --with-key`; never in a flag, output or file. `kenso api` only when no command fits. Flags: `kenso <resource> <action> --help`. More: `kenso docs leads|batch|crm|studio`.