From 6b58375a293f82403a6565634c2db87e10160f57 Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 23:49:34 +0100 Subject: [PATCH 1/2] docs(readme): say why, what and how, with two quick-start paths Rework the README with the best ideas from HKUDS/CLI-Anything's README: three gains under the banner, a quick start from an API description and from a wirecat.config.ts, why a CLI and MCP with a table of agents, a pain-to-fix table, how it works from the description to cli-dev ready, the tests that come with it, the nine CLIs built with it, design principles, limitations and a roadmap. The banner, the GIF, the links row and the comparison stay. The only estimate (config coverage) is labelled as one. Co-Authored-By: Claude Opus 5.5 --- README.md | 254 +++++++++++++++++++++------- changes/docs-readme-why-what-how.md | 6 + 2 files changed, 203 insertions(+), 57 deletions(-) create mode 100644 changes/docs-readme-why-what-how.md diff --git a/README.md b/README.md index becee70..bf4f297 100644 --- a/README.md +++ b/README.md @@ -26,15 +26,31 @@ License: Apache 2.0

- + + +- **Your agent gets the whole API on day one.** Every operation of an OpenAPI 3, Swagger 2.0 or Google Discovery + description becomes a command, an MCP tool and a page of the agent skill. +- **You stay in charge of what it does.** Each command and each API operation has a permission, every delete has its + own, and the token stays in your system keyring. +- **The CLI keeps up after you edit it.** `upgrade` merges each template fix into your copy, and your own commands are + never touched. From PokeAPI's published description to 102 commands, a real answer and a working MCP server took 16 seconds with an empty pnpm store and 12 with a warm one, not counting npx's own download. Nine of WireCat's own CLIs are made from -it, among them [hubspot-cli](https://github.com/WireCatLabs/hubspot-cli) and [ydisk](https://github.com/WireCatLabs/ydisk), -which are on its latest version through its upgrade. +the template, see [CLIs built with it](#clis-built-with-it). ## Quick start +There are two ways in. Pick the one that fits what you have. + +| You have | Start with | You get | +| --- | --- | --- | +| The address of the service's API description | `new --spec-url ` | A CLI with one command per operation, the MCP server and the skill | +| An API description and a few lines saying how its records map to people and companies | `new --from-config wirecat.config.ts` | The same, plus sign-in, `sync` into a local copy and the category's contract tests (CRM today) | +| An agent and no time | `npx skills add WireCatLabs/cli-template` | Your agent finds the description and runs one of the two above | + +### From an API description + ```sh npx @wirecat/cli-template new poke-cli --preset generic --owner example --sign-in none \ --spec-url https://raw.githubusercontent.com/PokeAPI/pokeapi/d19c710/openapi.yml @@ -47,44 +63,175 @@ Put your own GitHub name in `--owner` and the address of your service's descript `--preset generic` answers the questions only WireCat's own tools need, and any flag you give wins. Without it, `new` asks for every missing answer and never guesses one. -```mermaid -flowchart LR - spec["API description
OpenAPI 3 or Swagger 2.0, JSON or YAML,
or Google Discovery"] -->|new, generate| cli["Your CLI
one command per operation"] - cli --> mcp["MCP server"] - cli --> skill["Agent skill"] - mcp --> apps["Claude Code, Codex
or any app that speaks MCP"] - skill --> apps +### From a config + +One file says which service it is, where its API description lives, how to check a token, and how the service's +records map to people, companies and deals. `new` builds the CLI from it, and the CLI keeps the file as the one place +to edit. + +```ts +import { defineCli } from "@wirecat/cli-core/manifest" + +export default defineCli({ + identity: { command: "acme", package: "@wirecat/acme-cli", prefix: "WCACME", service: "Acme", owner: "WireCatLabs" }, + spec: { kind: "openapi", from: "https://acme.example/openapi.json" }, + auth: { preset: "token", verify: { operation: "getMe", id: "workspace.id", name: "workspace.name" } }, + category: "crm", + source: { provider: "acme", kinds: ["person"], entities: { person: { … } } }, +}) +``` + +```sh +npx @wirecat/cli-template new --from-config wirecat.config.ts +cd acme-cli && pnpm install && pnpm generate +node dist/bin/acme.js work session start # takes the token and checks it with auth.verify +node dist/bin/acme.js work sync # copies the records in, then only what changed ``` +This path needs a real account and its token, since `session start` checks the token against the service. The fields +of `source` are in the [kit reference](kit/README.md#new-name). + +## Why a CLI and MCP + +- **An agent with a terminal runs it like you do.** Claude Code or Codex read `--help`, ask `--json=name,height` for + only the fields they need, and chain commands in a script. +- **An app without a terminal gets the same commands over MCP.** Claude Desktop, Cursor and others connect to + `mcp serve`, and ChatGPT or Claude in the browser through `mcp serve --http` behind your own tunnel. +- **You can repeat what the agent did.** It is the same command, with the same permissions, so you check a result by + running it yourself. A command that fails is kept as a run, and `runs show` tells you what was run. + +| Agent | How to connect | +| --- | --- | +| Claude Code, Codex | ` mcp add claude-code` or `mcp add codex`, and ` skill install` | +| Claude Desktop, Cursor | ` mcp config` prints the entry to paste | +| ChatGPT, Claude in the browser | ` mcp serve --http --public-url ` | +| Gemini CLI, OpenClaw, Hermes | ` skill install --for agents` (or `--for hermes`) | + +## What it fixes + +| What goes wrong with an API wrapper | What the template does | +| --- | --- | +| You edit the generated code, and the next run of the generator writes over it | `upgrade` merges each template change file by file and asks before it touches a file you changed | +| An agent deletes something you did not mean it to | Each profile sets `allow`, `ask`, `readonly` or `deny` per command and per API operation. A delete needs its own permission key, and the api group refuses to build without one. `--dry-run` shows what would run | +| The token sits in a `.env` file | It stays in the OS keyring, under a profile you name, such as `personal` or `work`. No profile is ever assumed: a command without one stops and lists the profiles | +| The service changes its API | `pnpm spec:sync` downloads the description again, and `pnpm generate` follows | +| "It worked on my machine" | `src/api.test.ts` sends every operation to a fake built from the description, which refuses a request the description does not allow | + ## What you get ```text poke-cli/ -├── spec/poke/openapi.yaml the API description, and where it came from -├── src/generated/ types, schemas and a manifest of every operation -├── src/commands/ the api group, the sign-in and your own commands -├── src/api.test.ts every operation sent to a strict fake of the API -├── skills/ the agent skill, with pages for the API -├── .github/workflows/ CI, the release and a monthly check -└── bin/release publishes each version to npm through GitHub +├── spec/poke/openapi.yaml the API description, and where it came from +├── wirecat.config.ts with --from-config: the one file to edit +├── src/generated/ types, schemas and a manifest of every operation +├── src/commands/ the api group, the sign-in and your own commands +├── src/hooks.ts with --from-config: the service's own logic the config cannot say +├── src/api.test.ts every operation sent to a strict fake of the API +├── src/crm-contracts.test.ts with a CRM config: cli-core's contracts for the category +├── contracts/wirecat.json what WireCat Desktop reads to show and run the tool +├── skills/ the agent skill, with pages for the API +├── .github/workflows/ CI, the release and a monthly check +└── bin/release publishes each version to npm through GitHub +``` + +A CLI with a source, such as a CRM made from a config, also gets what cli-core gives every WireCat tool. It keeps a +local copy that `sync` updates with only the changes, so lists and search answer with no request to the service, also +offline. Its people and companies join the same people from your other WireCat tools, and `search all` finds them +together. A CLI made only from a description has no store and no search, it calls the service live. + +## How it works + +```mermaid +flowchart LR + spec["API description
OpenAPI 3, Swagger 2.0
or Google Discovery"] --> config["wirecat.config.ts
sign-in, category,
field map"] + config --> hooks["src/hooks.ts
what the config
cannot say"] + hooks --> ready["cli-dev ready
every check,
with its evidence"] + ready --> live["live check
on a test account"] + live --> release["bin/release
npm"] ``` -- **Your agent gets the API the day you start.** `poke personal mcp serve` serves every command to an agent over MCP, - and `poke skill install` teaches Claude Code, Codex or Gemini CLI how to use the tool. -- **The token stays in the OS keyring**, under a profile you name, such as `personal` or `work`. No profile is ever - assumed: a command without one stops and lists the profiles. +1. **The description.** `new --spec-url` downloads it (https only, at most 20 MB), puts its servers into the hosts + the CLI may reach, and records the address and a hash in `spec//provenance.json`. `pnpm generate` writes + one command per operation, its permission, its test and the skill's page. When the generator stops on part of the + description, it names the place. Add a patch with its reason in `scripts/spec-model.ts`, as the + [OpenAPI guide](kit/skills/new-cli/references/openapi.md) shows. +2. **The config.** `wirecat.config.ts` says how to check a token and how the service's answers map to people, + companies and deals. `pnpm generate` turns it into code that cli-core runs, so paging, cursors, the request budget and the store come from + cli-core, not from code you write. +3. **The hooks.** What only this service does goes into `src/hooks.ts`, such as dropping old values of a field that + keeps its history. The config names the file, and `pnpm source:check` checks every operation and path the config + reads against the generated API. +4. **`cli-dev ready`.** It runs the CLI's checks in a fixed order and says for each one whether it is verified, with + the evidence, and the one next step. A row is verified only by a script that passed, or by a live-check record of + exactly this code. Nothing is inferred. +5. **The live check and the release.** `bin/live ` runs `scripts/live.sh` against a test account and records + the pass. `bin/release` publishes to npm through GitHub. + +How much of a source a config could cover, we estimated by reading the code of five WireCat CLIs written by hand +before the config existed (an estimate, give or take 10 points): about 60% of HubSpot's, 75% of Yandex Disk's and 87% +of Google Drive's. The rest is the service's own logic, and it stays in hooks. + +## Tests that come with it + +| Layer | What it proves | Where | +| --- | --- | --- | +| Every operation | The request each command sends is one the description allows, and a denied delete stops before anything is sent | `src/api.test.ts` | +| Sign-in | `session start` checks the token with the operation the config names, and keeps nothing when the service refuses it | `src/commands/session.test.ts` | +| Category contracts | The source behaves like every CRM in WireCat, faults included. For example "a full list cut after its first page goes on from that page in a new run, nothing lost or repeated" and "a clock off by ten minutes either way loses no change" | `src/crm-contracts.test.ts`, from cli-core | +| Ready | Every check before a release ran and passed on this code | `pnpm exec cli-dev ready` | +| Live | The CLI works against the real service | `bin/live`, on a test account | + +cli-core has contracts for CRM, files, calendar, mail and meetings. A config wires CRM's today. For the others you +write the source by hand and run the same contracts. + +## CLIs built with it + +All of them are WireCat's own, public, and made from this template. + +| CLI | What it does | +| --- | --- | +| [hubspot-cli](https://github.com/WireCatLabs/hubspot-cli) | HubSpot CRM: a local copy of deals, contacts and companies, an MCP server and every CRM read of HubSpot's API | +| [bitrix24-cli](https://github.com/WireCatLabs/bitrix24-cli) | Bitrix24 CRM: deals and leads in a local store, any REST method, a permission on every write | +| [amo-cli](https://github.com/WireCatLabs/amo-cli) | amoCRM and Kommo: deals in a local store, any API v4 operation, a permission on every write | +| [notion-cli](https://github.com/WireCatLabs/notion-cli) | Notion pages and databases, searchable on your computer | +| [ydisk-cli](https://github.com/WireCatLabs/ydisk-cli) | Yandex Disk: search the folders you choose, and work with the files live | +| [mail-cli](https://github.com/WireCatLabs/mail-cli) | Any IMAP mailbox copied to your computer and searchable offline, sending over SMTP | +| [gcal-cli](https://github.com/WireCatLabs/gcal-cli) | Google Calendar for you and your agent | +| [beeline-cli](https://github.com/WireCatLabs/beeline-cli) | Beeline Cloud PBX: call records synced, recordings transcribed on your computer | +| [asterisk-cli](https://github.com/WireCatLabs/asterisk-cli) | Asterisk calls for your agent | + +## Design principles + +- **Nothing is guessed.** No account or profile is ever picked for you, and `new` asks for every missing answer. A + missing profile is an error that lists the choices. +- **You set what an agent may write.** Every command and API operation has a permission key, a delete has its own, + and an MCP server can only make them stricter. `readonly` or `deny` stops a write before anything is sent. +- **One set of commands, three ways in.** The CLI, the MCP tools and the skill come from the same commands, so what + you test is what the agent runs. +- **Shared work lives in one place.** The store, search, MCP and permissions come from cli-core, so a fix there + reaches every CLI with its next update. A CLI does not write them again. +- **Proven, not assumed.** A check counts when its script passed on this code, and the live check runs on a real + account before a release. + +## Have an agent build it + +```sh +npx skills add WireCatLabs/cli-template +``` + +This installs the [api-to-cli skill](SKILL.md) for Claude Code, Codex and other agents. Ask your agent for a CLI for +a service, and it finds the description, runs `new`, fixes what the generator stops on, and wires the MCP server. It +never runs the CLI against your account without asking. WireCat's own CLIs use the longer +[new-cli skill](kit/skills/new-cli/SKILL.md), which also keeps the research and the reviews, and has a fresh agent +review each slice of work. -## Why cli-template +What we learned building nine CLIs, and wrote into that skill: -- **It keeps up after you edit.** `upgrade` merges each template change into your CLI file by file, and asks before - it touches a file you changed. A one-time generator leaves you to copy its later fixes by hand. -- **One set of commands, three ways in.** The same commands are the CLI, the MCP tools and the skill, so what you - test is what the agent runs. -- **You decide what an agent may do.** Each profile sets `allow`, `readonly` or `deny` per command and per API - operation. An operation that deletes needs its own permission key, and the api group refuses to build without one. -- **Tests come with the API.** `src/api.test.ts` sends every operation to a fake built from the description, which - refuses a request the description does not allow. It also checks that a denied delete stops before anything is sent. -- **Google APIs too.** Besides OpenAPI 3 and Swagger 2.0 it reads Google's Discovery documents. +- **Patch the description, with its reason.** A service's description is often wrong in small places. A patch in + `scripts/spec-model.ts` with a comment beats a fix in generated code that the next `generate` loses. +- **One file maps the service's answers.** When the service changes a field, one file and one contract test break, + not ten commands. +- **Two agents never write the same file.** notion-cli once ended up with two fakes of the same API that way. ## How it compares @@ -98,21 +245,26 @@ Checked on the tools' own pages in November 2026. "Not documented" means the pag | [FastMCP `from_openapi`](https://gofastmcp.com/integrations/openapi) | An MCP server built at run time, in Python | MCP only | No code is generated | Not documented | Apache-2.0 | | [api2cli](https://github.com/alexknowshtml/api2cli) | A Commander.js CLI and a skill, written by a Claude Code skill | A Claude Code skill | A one-time result | None shown | MIT | -What cli-template does not do. It is Node and TypeScript only (Node 22.16 or 24 and later, with pnpm), and it -builds no single binary. The api group calls one base URL, and its generator stops on a keyword it does not -understand, so some descriptions need a patch with its reason before they generate. The CLI signs in with a token: OAuth is yours to wire up, from cli-core's `oauth` module. The skeleton keeps -no data of its own and has no search. +## Limitations -## From your API description +- **Node and TypeScript only.** Node 22.16 or 24 and later, with pnpm. It builds no single binary. +- **Some of it stays hand-written.** What only one service does goes into hooks. Writes to a CRM, OAuth sign-in and + services without an OpenAPI description (Bitrix24's RPC methods, for example) are code you write, with cli-core's + helpers. The CLI signs in with a token by default: OAuth is yours to wire up, from cli-core's `oauth` module. +- **A config covers CRM sources today.** Other categories need their source written by hand. +- **The live check needs a test account.** WireCat's own CLIs need it before every release. A CLI made with + `--preset generic` may skip it, and you then release without proof the CLI works against the real service. +- **One base URL.** The api group calls one base URL, and the generator stops on a keyword it does not understand, so + some descriptions need a patch before they generate. -`new --spec-url ` downloads the description (https only, at most 20 MB), puts its servers into the hosts the -CLI may reach, and records the address and a hash in `spec//provenance.json`. `pnpm generate` then writes -one command per operation, its permissions, its tests and the skill's API pages. +## Roadmap -When the generator stops on part of the description, it names the place. Add a patch with its reason in -`scripts/spec-model.ts`, or set what to treat as a delete in `scripts/generate.ts`, as the -[OpenAPI guide](kit/skills/new-cli/references/openapi.md) shows. When the service changes its API, `pnpm spec:sync` -downloads it again and `pnpm generate` follows. +- **GraphQL in `new`.** cli-core and cli-base already send GraphQL operations through the api group. `new` does not + take a GraphQL schema yet. +- **Configs for more categories,** starting with files and documents, where Drive and Yandex Disk show the most to + gain. +- **OAuth from the description.** The sign-in built from the description's `securitySchemes`, not by hand. +- **RPC services.** A config for services like Bitrix24 that have methods in place of paths. ## Keep it current @@ -122,24 +274,12 @@ each file would get and writes nothing. The files that are yours from the start, `src/commands/`, `README.md` and `package.json`, are never touched. The details are in the [kit reference](kit/README.md#upgrade). -## Have an agent build it - -```sh -npx skills add WireCatLabs/cli-template -``` - -This installs the [api-to-cli skill](SKILL.md) for Claude Code, Codex and other agents. Ask your agent for a CLI for -a service, and it finds the description, runs `new`, fixes what the generator stops on, and wires the MCP server. It -never runs the CLI against your account without asking. WireCat's own CLIs use the longer -[new-cli skill](kit/skills/new-cli/SKILL.md), which also keeps the research and reviews in WireCat's repositories. - ## Publishing outside WireCat A CLI made outside WireCat publishes under its own npm scope, such as `@example/poke-cli`. `new --preset generic` sets it up for that, with its own MCP Registry name and its own monthly CI run, and no recorded live check before a -release. `bin/setup-github` creates the -repository, and `bin/release --first` publishes the first version from your computer. The steps, with npm trusted -publishing, are in [Publishing outside WireCat](kit/README.md#publishing-outside-wirecat). +release. `bin/setup-github` creates the repository, and `bin/release --first` publishes the first version from your +computer. The steps, with npm trusted publishing, are in [Publishing outside WireCat](kit/README.md#publishing-outside-wirecat). ## This repository is also the skeleton diff --git a/changes/docs-readme-why-what-how.md b/changes/docs-readme-why-what-how.md new file mode 100644 index 0000000..6b060d3 --- /dev/null +++ b/changes/docs-readme-why-what-how.md @@ -0,0 +1,6 @@ +### Added + +- **The README says why, what and how.** Three gains under the banner, a quick start with two paths (from an API + description and from a config), why a CLI and MCP with a table of agents, what it fixes, how it works from the + description to `cli-dev ready`, the tests that come with it, the nine CLIs built with it, design principles, + limitations and a roadmap ([README](../README.md)). From 111893ba4483d7352afdec878847cffecc04b80f Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 23:59:01 +0100 Subject: [PATCH 2/2] docs(readme): fix the claims a review found against the code - mcp add needs --allow-writes for a profile that may write, in the template's quick start and in a new CLI's README - an operation is a command the MCP server runs, not an MCP tool each - upgrade merges CI, release and agent files; cli-core brings code fixes - ask runs over MCP, so the profile served there wants readonly or deny - the api-to-cli skill runs new --spec-url, not --from-config - GraphQL: cli-base generates, cli-core's next release sends - src/hooks.ts is yours to add; the live check binds WireCat's CLIs - the coverage estimate gives the whole range, 42% to 87% - Discovery goes through --spec discovery, not --spec-url Co-Authored-By: Claude Opus 5.5 --- README.md | 60 ++++++++++++++++------------- changes/docs-readme-why-what-how.md | 2 + kit/src/new.ts | 5 ++- 3 files changed, 39 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index bf4f297..bee1dc9 100644 --- a/README.md +++ b/README.md @@ -29,11 +29,11 @@ - **Your agent gets the whole API on day one.** Every operation of an OpenAPI 3, Swagger 2.0 or Google Discovery - description becomes a command, an MCP tool and a page of the agent skill. + description becomes a command that the MCP server and the agent skill run, with a page in the skill. - **You stay in charge of what it does.** Each command and each API operation has a permission, every delete has its own, and the token stays in your system keyring. -- **The CLI keeps up after you edit it.** `upgrade` merges each template fix into your copy, and your own commands are - never touched. +- **The CLI keeps up after you edit it.** `upgrade` merges the template's CI, release and agent files into your copy, + and updates of cli-core bring the fixes to the code. Your own commands are never touched. From PokeAPI's published description to 102 commands, a real answer and a working MCP server took 16 seconds with an empty pnpm store and 12 with a warm one, not counting npx's own download. Nine of WireCat's own CLIs are made from @@ -47,7 +47,7 @@ There are two ways in. Pick the one that fits what you have. | --- | --- | --- | | The address of the service's API description | `new --spec-url ` | A CLI with one command per operation, the MCP server and the skill | | An API description and a few lines saying how its records map to people and companies | `new --from-config wirecat.config.ts` | The same, plus sign-in, `sync` into a local copy and the category's contract tests (CRM today) | -| An agent and no time | `npx skills add WireCatLabs/cli-template` | Your agent finds the description and runs one of the two above | +| An agent and no time | `npx skills add WireCatLabs/cli-template` | Your agent finds the description and runs `new --spec-url` for you | ### From an API description @@ -56,12 +56,14 @@ npx @wirecat/cli-template new poke-cli --preset generic --owner example --sign-i --spec-url https://raw.githubusercontent.com/PokeAPI/pokeapi/d19c710/openapi.yml cd poke-cli && pnpm install && pnpm generate node dist/bin/poke.js personal api pokemon-get --id pikachu --json=name,height,weight -node dist/bin/poke.js personal mcp add claude-code +node dist/bin/poke.js personal mcp add claude-code --allow-writes ``` Put your own GitHub name in `--owner` and the address of your service's description in `--spec-url`, JSON or YAML. `--preset generic` answers the questions only WireCat's own tools need, and any flag you give wins. Without it, `new` -asks for every missing answer and never guesses one. +asks for every missing answer and never guesses one. `--allow-writes` is there because the template's sample +`comments` commands can write, and `mcp add` refuses a profile with writes until you say so. +`npx @wirecat/cli-template remove-sample` drops the sample. ### From a config @@ -88,8 +90,11 @@ node dist/bin/acme.js work session start # takes the token and checks it with node dist/bin/acme.js work sync # copies the records in, then only what changed ``` -This path needs a real account and its token, since `session start` checks the token against the service. The fields -of `source` are in the [kit reference](kit/README.md#new-name). +In a terminal, `new` asks for the answers the config does not hold, such as the content languages. A script or an +agent passes them as flags, listed in the [kit reference](kit/README.md#new-name). Outside WireCat, use your own +scope in `package` and your own name in `owner`. This path needs a real account and its token, since +`session start` checks the token against the service. The shape of `source` is `CrmManifest` in +`@wirecat/cli-core/manifest`. ## Why a CLI and MCP @@ -102,7 +107,7 @@ of `source` are in the [kit reference](kit/README.md#new-name). | Agent | How to connect | | --- | --- | -| Claude Code, Codex | ` mcp add claude-code` or `mcp add codex`, and ` skill install` | +| Claude Code, Codex | ` mcp add claude-code` or `mcp add codex` (`--allow-writes` for a profile that may write), and ` skill install` | | Claude Desktop, Cursor | ` mcp config` prints the entry to paste | | ChatGPT, Claude in the browser | ` mcp serve --http --public-url ` | | Gemini CLI, OpenClaw, Hermes | ` skill install --for agents` (or `--for hermes`) | @@ -111,8 +116,8 @@ of `source` are in the [kit reference](kit/README.md#new-name). | What goes wrong with an API wrapper | What the template does | | --- | --- | -| You edit the generated code, and the next run of the generator writes over it | `upgrade` merges each template change file by file and asks before it touches a file you changed | -| An agent deletes something you did not mean it to | Each profile sets `allow`, `ask`, `readonly` or `deny` per command and per API operation. A delete needs its own permission key, and the api group refuses to build without one. `--dry-run` shows what would run | +| A one-time generator leaves you to copy its later fixes by hand | `upgrade` merges each template change file by file and asks before it touches a file you changed. `src/`, `scripts/` and `docs/` are yours and never touched | +| An agent deletes something you did not mean it to | Each profile sets `allow`, `ask`, `readonly` or `deny` per command and per API operation. A delete needs its own permission key, and the api group refuses to start without one. `--dry-run` shows what would run. Over MCP nobody can answer `ask`, so it runs: give the profile you serve `readonly` or `deny` where it matters | | The token sits in a `.env` file | It stays in the OS keyring, under a profile you name, such as `personal` or `work`. No profile is ever assumed: a command without one stops and lists the profiles | | The service changes its API | `pnpm spec:sync` downloads the description again, and `pnpm generate` follows | | "It worked on my machine" | `src/api.test.ts` sends every operation to a fake built from the description, which refuses a request the description does not allow | @@ -125,7 +130,7 @@ poke-cli/ ├── wirecat.config.ts with --from-config: the one file to edit ├── src/generated/ types, schemas and a manifest of every operation ├── src/commands/ the api group, the sign-in and your own commands -├── src/hooks.ts with --from-config: the service's own logic the config cannot say +├── src/hooks.ts yours to add, named by `hooks` in the config: what the config cannot say ├── src/api.test.ts every operation sent to a strict fake of the API ├── src/crm-contracts.test.ts with a CRM config: cli-core's contracts for the category ├── contracts/wirecat.json what WireCat Desktop reads to show and run the tool @@ -135,9 +140,9 @@ poke-cli/ ``` A CLI with a source, such as a CRM made from a config, also gets what cli-core gives every WireCat tool. It keeps a -local copy that `sync` updates with only the changes, so lists and search answer with no request to the service, also -offline. Its people and companies join the same people from your other WireCat tools, and `search all` finds them -together. A CLI made only from a description has no store and no search, it calls the service live. +local copy that `sync` updates with only the changes, so its lists and search can answer from the copy, also +offline. A contact joins a person from your other WireCat tools by the same email, and `search all` finds them +together. A CLI made only from a description has no store and no search. It calls the service live. ## How it works @@ -150,14 +155,16 @@ flowchart LR live --> release["bin/release
npm"] ``` -1. **The description.** `new --spec-url` downloads it (https only, at most 20 MB), puts its servers into the hosts +1. **The description.** `new --spec-url` downloads an OpenAPI 3 or Swagger 2.0 description (https, or http from + localhost, at most 20 MB), puts its servers into the hosts the CLI may reach, and records the address and a hash in `spec//provenance.json`. `pnpm generate` writes one command per operation, its permission, its test and the skill's page. When the generator stops on part of the description, it names the place. Add a patch with its reason in `scripts/spec-model.ts`, as the - [OpenAPI guide](kit/skills/new-cli/references/openapi.md) shows. + [OpenAPI guide](kit/skills/new-cli/references/openapi.md) shows. A Google Discovery document goes in with + `--spec discovery` and a line in `scripts/sync-spec.ts`. 2. **The config.** `wirecat.config.ts` says how to check a token and how the service's answers map to people, - companies and deals. `pnpm generate` turns it into code that cli-core runs, so paging, cursors, the request budget and the store come from - cli-core, not from code you write. + companies and deals. `pnpm generate` turns it into code that cli-core runs, so paging, cursors, the request budget + and the store come from cli-core, not from code you write. 3. **The hooks.** What only this service does goes into `src/hooks.ts`, such as dropping old values of a field that keeps its history. The config names the file, and `pnpm source:check` checks every operation and path the config reads against the generated API. @@ -168,15 +175,16 @@ flowchart LR the pass. `bin/release` publishes to npm through GitHub. How much of a source a config could cover, we estimated by reading the code of five WireCat CLIs written by hand -before the config existed (an estimate, give or take 10 points): about 60% of HubSpot's, 75% of Yandex Disk's and 87% -of Google Drive's. The rest is the service's own logic, and it stays in hooks. +before the config existed (an estimate, give or take 10 points): between 42% (Bitrix24) and 87% (Google Drive), +with HubSpot at about 60%. The rest is the service's own logic, and it stays in hooks. Drive and Yandex Disk are +document sources, which a config does not cover yet. ## Tests that come with it | Layer | What it proves | Where | | --- | --- | --- | | Every operation | The request each command sends is one the description allows, and a denied delete stops before anything is sent | `src/api.test.ts` | -| Sign-in | `session start` checks the token with the operation the config names, and keeps nothing when the service refuses it | `src/commands/session.test.ts` | +| Sign-in, with `auth.verify` | `session start` checks the token with the operation the config names, and keeps nothing when the service refuses it | `src/commands/session.test.ts` | | Category contracts | The source behaves like every CRM in WireCat, faults included. For example "a full list cut after its first page goes on from that page in a new run, nothing lost or repeated" and "a clock off by ten minutes either way loses no change" | `src/crm-contracts.test.ts`, from cli-core | | Ready | Every check before a release ran and passed on this code | `pnpm exec cli-dev ready` | | Live | The CLI works against the real service | `bin/live`, on a test account | @@ -210,8 +218,8 @@ All of them are WireCat's own, public, and made from this template. you test is what the agent runs. - **Shared work lives in one place.** The store, search, MCP and permissions come from cli-core, so a fix there reaches every CLI with its next update. A CLI does not write them again. -- **Proven, not assumed.** A check counts when its script passed on this code, and the live check runs on a real - account before a release. +- **Proven, not assumed.** A check counts when its script passed on this code. WireCat's own CLIs also pass the live + check on a real account before each release. ## Have an agent build it @@ -259,8 +267,8 @@ Checked on the tools' own pages in November 2026. "Not documented" means the pag ## Roadmap -- **GraphQL in `new`.** cli-core and cli-base already send GraphQL operations through the api group. `new` does not - take a GraphQL schema yet. +- **GraphQL in `new`.** cli-base already generates commands from a GraphQL schema, and cli-core's next release + sends the calls. `new` does not take a GraphQL schema yet. - **Configs for more categories,** starting with files and documents, where Drive and Yandex Disk show the most to gain. - **OAuth from the description.** The sign-in built from the description's `securitySchemes`, not by hand. diff --git a/changes/docs-readme-why-what-how.md b/changes/docs-readme-why-what-how.md index 6b060d3..887131e 100644 --- a/changes/docs-readme-why-what-how.md +++ b/changes/docs-readme-why-what-how.md @@ -4,3 +4,5 @@ description and from a config), why a CLI and MCP with a table of agents, what it fixes, how it works from the description to `cli-dev ready`, the tests that come with it, the nine CLIs built with it, design principles, limitations and a roadmap ([README](../README.md)). +- **A new CLI's README says when `mcp add` needs `--allow-writes`**: for a profile whose tools may write, after a + review of its permissions. diff --git a/kit/src/new.ts b/kit/src/new.ts index e23d1b0..db7424b 100644 --- a/kit/src/new.ts +++ b/kit/src/new.ts @@ -593,8 +593,9 @@ export const cliReadme = (names: Names, facts: ReadmeFacts): string => { `${cli} skill install`, "```", "", - `\`${cli} personal mcp check\` shows the tools your agent gets. \`${cli} personal mcp config\` prints the setup for any`, - "other MCP client.", + `\`${cli} personal mcp check\` shows the tools your agent gets. \`mcp add\` refuses a profile whose tools may write`, + `until you review its permissions and pass \`--allow-writes\`. \`${cli} personal mcp config\` prints the setup for`, + "any other MCP client.", "", "## What it can do", "",