kenso 0.0.0-stage → 0.1.8

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# kenso
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command line for [Kenso](https://ken.so): bulk lead, CRM and Studio work for people and coding agents.
+
+`kenso` takes a file and does the bulk work in your Kenso workspace: add 20,000 leads to a campaign with their custom variables, update or clean them up, import accounts and people, fill Studio templates. Every command prints JSON for scripts and agents. The bulk commands plan before they write and keep a per-row results file you can resume from. Every API operation a workspace member can call is a command too.
+
+- **CLI:** volume and files. Rows never pass through an agent's context: the agent passes a file path and reads a short summary.
+- **MCP** (`https://mcp.ken.so/mcp`): conversation and single records, with OAuth and no install.
+- **Both** use the same API, keys and permissions. `kenso mcp call` reaches MCP-only tools from the shell.
+
+## Install
+
+```bash
+npm i -g kenso
+```
+
+Or without installing: `npx kenso --help`.
+
+## Log in
+
+Create an API key in app.ken.so at Settings > Integrations > API keys, then:
+
+```bash
+echo $KEY | kenso auth login --with-key
+```
+
+That is also the way in for CI and agents, or set `KENSO_API_KEY` in their environment and skip the login. Browser login (`kenso auth login`) works when your workspace has it; until then it points you to `--with-key`.
+
+## 60-second quickstart
+
+```bash
+kenso workspace use 1234
+kenso campaigns list --limit 5
+kenso contacts import --template
+kenso contacts import --campaign 812 --file leads.csv --dry-run
+kenso contacts import --campaign 812 --file leads.csv --yes
+```
+
+The dry run checks every row and prints the plan, the credit estimate and the exact apply command. The apply prints one JSON summary, `created`, `updated`, `skipped` by reason, `failed`, and the path of `results.csv` with one line per input row. After Ctrl-C or a crash, run the same command again and it resumes where it stopped. Sending a row twice never creates a second lead.
+
+## Commands
+
+| Group | Commands |
+|---|---|
+| Leads | `contacts import`, `update`, `remove`, `restore`, `pause`, `resume`, `tag`, `untag`, `export` (`leads` is an alias of `contacts`) |
+| CRM (beta) | `accounts import`, `people import` |
+| Studio (beta) | `studio pull`, `push`, `validate`, `preview`, `fill` |
+| Runs | `runs list`, `show`, `resume`, `jobs wait` |
+| Setup | `auth login`, `logout`, `status`, `workspace list`, `use`, `doctor`, `skill install`, `docs` |
+| Everything else | `kenso <resource> <action>` for every API operation, `kenso api <METHOD> <path>`, `kenso mcp tools`, `mcp call` |
+| Discovery | `kenso --help`, `kenso <resource> --help`, `kenso describe` (JSON) |
+
+## Docs
+
+The docs ship in the package and print offline with `kenso docs <topic>`.
+
+- [Overview and quickstart](docs/README.md)
+- [Authentication](docs/auth.md)
+- [Leads: import, update, cleanup](docs/leads.md)
+- [Batch runs: dry run, results, resume, rate limits](docs/batch.md)
+- [Output, errors and exit codes](docs/output-and-errors.md)
+- [CRM (beta)](docs/crm.md)
+- [Studio (beta)](docs/studio.md)
+- [Coding agents: Claude Code, Codex, Cursor](docs/agents.md)
+- Command reference: `kenso docs reference` prints every command with its flags (generated at build time; `docs/reference.md` in the installed package). `kenso describe` gives the same as JSON.
+
+For coding agents, `kenso skill install` installs the Agent Skill.
+
+## Requirements
+
+Node 22 or newer. macOS, Linux and Windows.
+
+## License
+
+MIT