@apicircle/cli 1.0.1 → 1.0.3

package/LICENSE

@@ -1,110 +1,110 @@
-API Circle Studio License
-Custom Source-Available License, v1.0
-
-Copyright (c) 2026 Deva Prakash ("Licensor")
-
-The source code in this repository ("the Software") is made available for
-the purposes of transparency, security review, contribution, and personal
-evaluation. This is NOT an open-source license as defined by the Open
-Source Initiative.
-
-0. Definitions
-
-   "Commercial Use" means any use of the Software that is intended for
-   or directed toward commercial advantage or monetary compensation,
-   whether direct or indirect, including without limitation:
-
-   (a) using the Software to build, test, develop, deploy, or operate
-       any product, service, application, or system that is sold,
-       licensed, hosted, distributed, or otherwise made available to
-       any third party for a fee or other consideration;
-   (b) using the Software in the course of paid employment, paid
-       consulting, paid contracting, freelance work, or any other
-       revenue-generating activity, regardless of whether the Software
-       itself is sold or transferred;
-   (c) using the Software internally within a for-profit organization
-       beyond the Evaluation Period defined below;
-   (d) integrating the Software, or any portion of it, into any tool,
-       pipeline, automation, or workflow that supports the commercial
-       operations of any business;
-   (e) using the Software to provide a hosted, managed, or embedded
-       service of any kind to a third party, whether free or paid.
-
-   "Non-Commercial Use" means any use that is not Commercial Use,
-   including personal hobby projects, individual learning, academic
-   research, classroom instruction, and good-faith contribution to
-   this repository.
-
-   "Evaluation Period" means a single, continuous period of up to
-   thirty (30) days during which a for-profit organization may
-   internally evaluate the Software at no charge. After the Evaluation
-   Period expires, any further use of the Software by that organization
-   constitutes Commercial Use and requires a separate commercial
-   license from the Licensor.
-
-1. Permitted Use
-
-   You may, without charge:
-
-   (a) view, read, and study the source code of the Software;
-   (b) run the Software, in source or compiled form, for your own
-       Non-Commercial Use, or for Commercial Use solely within the
-       Evaluation Period;
-   (c) submit improvements to the Software back to this repository via
-       pull request, subject to Section 3 (Contributions).
-
-2. Prohibited Use
-
-   Without prior written permission from the Licensor, you may NOT:
-
-   (a) make any Commercial Use of the Software, in whole or in part,
-       except during the Evaluation Period as defined in Section 0;
-   (b) redistribute the Software, in source or compiled form, whether
-       modified or unmodified, to any third party;
-   (c) sublicense, sell, rent, lease, or otherwise transfer the
-       Software or any rights granted herein;
-   (d) remove, obscure, or alter any copyright, trademark, attribution,
-       or license notice contained in the Software;
-   (e) use the names "API Circle", "API Circle Studio", or any related
-       logos or trademarks, except as required for accurate attribution.
-
-3. Contributions
-
-   By submitting any contribution (including but not limited to code,
-   documentation, or assets) to this repository, you grant the Licensor
-   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
-   license to use, modify, distribute, and relicense your contribution
-   under any terms, including the terms of this license or any future
-   version thereof.
-
-4. No Trademark License
-
-   This license does not grant permission to use the trade names,
-   trademarks, service marks, or product names of the Licensor, except
-   as required for reasonable and customary use in describing the
-   origin of the Software.
-
-5. Termination
-
-   The rights granted in Section 1 terminate automatically if you
-   breach any term of this license. Upon termination, you must cease
-   all use of the Software and destroy all copies in your possession.
-
-6. Disclaimer of Warranty
-
-   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
-   NON-INFRINGEMENT.
-
-7. Limitation of Liability
-
-   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
-   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
-   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
-   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-8. Commercial Licensing
-
-   For commercial licensing, redistribution, or any use not permitted
-   under Section 1, contact: apicircle365@gmail.com
+API Circle Studio License
+Custom Source-Available License, v1.0
+
+Copyright (c) 2026 Deva Prakash ("Licensor")
+
+The source code in this repository ("the Software") is made available for
+the purposes of transparency, security review, contribution, and personal
+evaluation. This is NOT an open-source license as defined by the Open
+Source Initiative.
+
+0. Definitions
+
+   "Commercial Use" means any use of the Software that is intended for
+   or directed toward commercial advantage or monetary compensation,
+   whether direct or indirect, including without limitation:
+
+   (a) using the Software to build, test, develop, deploy, or operate
+       any product, service, application, or system that is sold,
+       licensed, hosted, distributed, or otherwise made available to
+       any third party for a fee or other consideration;
+   (b) using the Software in the course of paid employment, paid
+       consulting, paid contracting, freelance work, or any other
+       revenue-generating activity, regardless of whether the Software
+       itself is sold or transferred;
+   (c) using the Software internally within a for-profit organization
+       beyond the Evaluation Period defined below;
+   (d) integrating the Software, or any portion of it, into any tool,
+       pipeline, automation, or workflow that supports the commercial
+       operations of any business;
+   (e) using the Software to provide a hosted, managed, or embedded
+       service of any kind to a third party, whether free or paid.
+
+   "Non-Commercial Use" means any use that is not Commercial Use,
+   including personal hobby projects, individual learning, academic
+   research, classroom instruction, and good-faith contribution to
+   this repository.
+
+   "Evaluation Period" means a single, continuous period of up to
+   thirty (30) days during which a for-profit organization may
+   internally evaluate the Software at no charge. After the Evaluation
+   Period expires, any further use of the Software by that organization
+   constitutes Commercial Use and requires a separate commercial
+   license from the Licensor.
+
+1. Permitted Use
+
+   You may, without charge:
+
+   (a) view, read, and study the source code of the Software;
+   (b) run the Software, in source or compiled form, for your own
+       Non-Commercial Use, or for Commercial Use solely within the
+       Evaluation Period;
+   (c) submit improvements to the Software back to this repository via
+       pull request, subject to Section 3 (Contributions).
+
+2. Prohibited Use
+
+   Without prior written permission from the Licensor, you may NOT:
+
+   (a) make any Commercial Use of the Software, in whole or in part,
+       except during the Evaluation Period as defined in Section 0;
+   (b) redistribute the Software, in source or compiled form, whether
+       modified or unmodified, to any third party;
+   (c) sublicense, sell, rent, lease, or otherwise transfer the
+       Software or any rights granted herein;
+   (d) remove, obscure, or alter any copyright, trademark, attribution,
+       or license notice contained in the Software;
+   (e) use the names "API Circle", "API Circle Studio", or any related
+       logos or trademarks, except as required for accurate attribution.
+
+3. Contributions
+
+   By submitting any contribution (including but not limited to code,
+   documentation, or assets) to this repository, you grant the Licensor
+   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
+   license to use, modify, distribute, and relicense your contribution
+   under any terms, including the terms of this license or any future
+   version thereof.
+
+4. No Trademark License
+
+   This license does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except
+   as required for reasonable and customary use in describing the
+   origin of the Software.
+
+5. Termination
+
+   The rights granted in Section 1 terminate automatically if you
+   breach any term of this license. Upon termination, you must cease
+   all use of the Software and destroy all copies in your possession.
+
+6. Disclaimer of Warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. Commercial Licensing
+
+   For commercial licensing, redistribution, or any use not permitted
+   under Section 1, contact: apicircle365@gmail.com

package/README.md

@@ -4,41 +4,123 @@
 
 <h1 align="center">@apicircle/cli</h1>
 
-Command-line companion to [API Circle Studio](https://github.com/apicircle/studio). Run mock servers, drive the MCP server, import OpenAPI / Postman / Insomnia / curl into a workspace, and execute saved plans — all from any terminal, no Electron required.
+<p align="center">
+  <strong>API Circle Studio, without the UI.</strong><br />
+  Mock servers, MCP, spec imports, headless plan runs, and multi-workspace management — every Studio feature your team needs in CI, scripts, and SSH sessions.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@apicircle/cli"><img src="https://img.shields.io/npm/v/@apicircle/cli?color=cb3837&logo=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/subcommands-5-blue" alt="5 subcommands" />
+  <img src="https://img.shields.io/badge/runs-CI%20%C2%B7%20Docker%20%C2%B7%20SSH%20%C2%B7%20local-success" alt="Runs everywhere" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen" alt="Node ≥ 20" />
+</p>
+
+---
+
+## Why a CLI?
+
+The Studio desktop app is great for authoring. But the moment you want to
+**ship**, **schedule**, or **automate**, you need a binary. `@apicircle/cli`
+is exactly that — every workflow the desktop app supports, accessible from
+any terminal, container, or pipeline. No Electron, no GUI dependency, no
+mouse required.
+
+```bash
+# Spin up a mock from an OpenAPI spec — in one command
+apicircle mock ./openapi.yaml --port 4040
+
+# Run your saved smoke tests in CI, fail the build if they fail
+apicircle run "Smoke Tests" --reporter junit
+
+# Boot an MCP server so an AI assistant can drive your workspace
+apicircle mcp
+```
 
 ## Install
 
 ```bash
 npm install -g @apicircle/cli
-# or use without installing
+# or run without installing
 npx @apicircle/cli --help
 ```
 
-## What's a "workspace folder"?
+Single command, single binary: `apicircle`.
+
+## What you can do with it
+
+| You need to…                                      | Command                                                             |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| List, create, switch between workspaces           | `apicircle workspaces <list \| create \| use \| path>`              |
+| Run a local mock server from a spec file          | `apicircle mock <spec> [--port] [--type] [--cors]`                  |
+| Import a spec into a workspace                    | `apicircle import <openapi \| postman \| insomnia \| curl> <input>` |
+| Execute a saved plan headlessly                   | `apicircle run <plan>`                                              |
+| Expose your workspace to an AI assistant over MCP | `apicircle mcp [--workspace-name \| --workspace-path]`              |
 
-Several subcommands take `--workspace <dir>`. A _workspace folder_ is a
-directory containing two JSON files (`workspace.synced.json` and
-`workspace.local.json`) that together hold your collections, environments,
-mock-server definitions, and per-device runtime state.
+## Workspaces, in one minute
 
-**You get one by cloning a GitHub repo** created with the Desktop app's
-_Link to Git_ feature:
+API Circle Studio is **multi-workspace by default**. A workspace is a
+`{ synced, local }` pair of JSON documents — your collections, environments,
+mock-server definitions, plans, history. You can have many on a single
+machine; each is its own GitHub repo, environment set, etc.
+
+There are two ways the CLI finds a workspace:
+
+| Use case                                                           | How to point the CLI at it                                                                                   |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| Workspaces created in the desktop app on this machine              | `--workspace-name <name-or-id>` — registry lookup                                                            |
+| A workspace directory not registered locally (CI, git-cloned repo) | `--workspace-path <dir>` — literal filesystem path                                                           |
+| Whatever's currently active                                        | omit both — CLI picks the active workspace from the registry, or the current directory if no registry exists |
+
+The flags are **mutually exclusive** — passing both is an error.
+
+The registry root defaults to the desktop app's userData:
+
+- **Windows** — `%APPDATA%\@apicircle\desktop\workspaces\`
+- **macOS** — `~/Library/Application Support/@apicircle/desktop/workspaces/`
+- **Linux** — `~/.config/@apicircle/desktop/workspaces/`
+
+Override with `APICIRCLE_WORKSPACES_ROOT` for CI / tests.
+
+## Subcommands
+
+### `apicircle workspaces` — manage the registry
 
 ```bash
-git clone https://github.com/<you>/<your-workspace-repo>
-apicircle mcp --workspace ./<your-workspace-repo>
+apicircle workspaces list                          # every registered workspace + which is active
+apicircle workspaces list --json                   # JSON for scripts
+apicircle workspaces create "Petstore"             # seed a new workspace + add to the registry
+apicircle workspaces create "Sandbox" --sample     # seed with one sample request
+apicircle workspaces use Petstore                  # set the active workspace by name (or id)
+apicircle workspaces path Petstore                 # print the on-disk path for one workspace
+apicircle workspaces path                          # print the workspaces root
 ```
 
-If you don't have a workspace repo yet, open the **Desktop / Web app** —
-the workspace is created automatically in browser storage, and the **Mocks**
-and **MCP** panels work directly inside the app with no folder required. Use
-the CLI for headless / CI scenarios where on-disk JSON is the right interface.
+`workspaces use` resolves the same way as `--workspace-name`: case-insensitive
+name match, falling back to id.
 
-## Subcommands
+### `apicircle mcp` — boot the MCP stdio server
+
+```bash
+# Multi-workspace mode (recommended) — expose every workspace via `workspace.list`
+apicircle mcp
+
+# Scope to one workspace
+apicircle mcp --workspace-name Petstore
+
+# Point at a workspace directory that isn't in the registry (CI / git-cloned)
+apicircle mcp --workspace-path ./checkout-repo
+```
+
+With no workspace flag, the server boots against the desktop app's registry
+root and exposes **all** workspaces. AI clients see them through the
+`workspace.list` tool; entity tools default to the active workspace and accept
+an optional `workspaceId` to scope.
 
-### `apicircle mock <spec>`
+Wire this into Claude Desktop / Cursor / Codex / etc — see
+[Connect your AI client](https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md).
 
-Boot a mock server from an OpenAPI / Postman / Insomnia file.
+### `apicircle mock <spec>` — local mock server
 
 ```bash
 apicircle mock ./openapi.yaml --port 4040
@@ -46,46 +128,134 @@ apicircle mock ./postman_collection.json --type postman
 apicircle mock ./insomnia_export.json --type insomnia --cors=false
 ```
 
-The CLI binds to a free port unless `--port` is set, prints the URL, and runs until you `Ctrl-C`.
+The CLI binds to a free port unless `--port` is set, prints the URL, and runs
+until you `Ctrl-C`. This subcommand operates on a spec file directly — it does
+**not** consult the workspace registry.
 
-### `apicircle mcp [--workspace <dir>]`
+Under the hood: `@apicircle/mock-server-core`, the same Hono engine the
+desktop app uses.
 
-Start the MCP stdio server pointed at a workspace folder.
+### `apicircle import <type> <input>` — import a spec
 
 ```bash
-apicircle mcp --workspace ./my-workspace
-APICIRCLE_WORKSPACE=./my-workspace apicircle mcp
-```
+# Active workspace (or current directory when no registry exists)
+apicircle import openapi ./spec.yaml --format yaml
+
+# Named registered workspace
+apicircle import postman ./col.json --workspace-name Petstore
+apicircle import insomnia ./exp.json --workspace-name Petstore
 
-If `--workspace` is omitted, the current directory is used. The directory is auto-initialized with an empty `workspace.synced.json` + `workspace.local.json` on first run.
+# Workspace dir not in the registry
+apicircle import openapi ./spec.yaml --workspace-path ./checkout-repo
 
-Wire this into Claude Desktop / Cursor / etc — see [Connect your AI client](https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md).
+# Read from stdin
+apicircle import openapi - --workspace-name Petstore < ./spec.yaml
+```
 
-### `apicircle import <type> <input>`
+`<type>` is `curl`, `openapi`, `postman`, or `insomnia`. Each import appends
+one request per operation / item — your existing folder structure stays intact.
 
-Import a spec into a workspace folder.
+### `apicircle run <plan>` — execute a saved plan headlessly
 
 ```bash
-apicircle import openapi  ./spec.yaml --workspace ./ws --format yaml
-apicircle import postman  ./col.json  --workspace ./ws
-apicircle import insomnia ./exp.json  --workspace ./ws
-apicircle import curl     ./curl.txt  --workspace ./ws
-apicircle import openapi  -           --workspace ./ws < ./spec.yaml
+apicircle run "Smoke Tests" --reporter junit
+apicircle run plan_a1b2c3 --env staging --bail --workspace-name Petstore
+apicircle run "Nightly" --secrets ./secrets.json --no-save
 ```
 
-Each import appends one request per operation/item to `workspace.synced.json`.
+Resolves a plan by name or id, runs each step through the **real** request
+engine (same auth, same retries, same assertions as the desktop app),
+evaluates assertions, and carries extracted context forward between steps.
+
+**Flags:**
+
+- `--reporter text|json|junit` — output format; `junit` is ready for CI test reporters.
+- `--bail` — stop at the first failed step.
+- `--env <name>` — layer an environment onto the run.
+- `--secrets <file>` or `APICIRCLE_SECRET_*` env vars — supply encrypted variables.
+- `--no-save` — don't write the run to history.
+- `--no-assertions` — execute requests but skip assertions.
+- `--as <actor>` — override the recorded runner identity.
+
+**Exit codes:** `0` every step passed, `1` a step failed (or the run was
+aborted), `2` usage error, `3` denied by the authorization gate. Pipelines
+gate on it directly.
 
-### `apicircle run <plan>`
+## Common workflows
 
-Execute a saved workspace execution plan headlessly and report pass/fail.
+**Set up a new workspace from scratch**
 
 ```bash
+apicircle workspaces create "Internal API"
+apicircle import openapi ./internal-api.yaml --workspace-name "Internal API"
+apicircle mcp --workspace-name "Internal API"
+```
+
+**CI gate against a git-cloned workspace repo**
+
+```bash
+git clone github.com/me/checkout-workspace.git
+cd checkout-workspace
 apicircle run "Smoke Tests" --reporter junit
-apicircle run plan_a1b2c3 --env staging --bail
-apicircle run "Nightly" --secrets ./secrets.json --no-save
 ```
 
-Resolves a plan by name or id, runs each step through the real request engine, evaluates assertions, and carries extracted context forward. Flags: `--reporter text|json|junit`, `--bail` (stop at the first failed step), `--env <name>` (layer an environment onto the run), `--secrets <file>` or `APICIRCLE_SECRET_*` env vars (encrypted variables), `--no-save`, `--no-assertions`. Exit codes: `0` pass, `1` fail, `2` usage error, `3` run denied.
+(No `--workspace-path` needed when running inside the workspace directory —
+the CLI's cwd fallback picks it up automatically.)
+
+**Mock a third-party API for the duration of your test suite**
+
+```bash
+apicircle mock ./stripe-openapi.yaml --port 4242 &
+MOCK_PID=$!
+
+npm test
+RESULT=$?
+
+kill $MOCK_PID
+exit $RESULT
+```
+
+**Switch the active workspace and verify**
+
+```bash
+apicircle workspaces use Sandbox
+apicircle workspaces list
+# Sandbox now shows ● next to it.
+```
+
+## Use cases
+
+- **CI / CD gates** — run smoke tests, contract tests, or full regression
+  plans against staging before promoting to prod.
+- **Mock-driven local dev** — `apicircle mock` in a side terminal, your
+  frontend pointed at it, your backend team unblocked.
+- **Headless onboarding** — `apicircle import openapi <url>` turns a public
+  spec into a typed, runnable workspace in seconds.
+- **AI-assistant wiring on servers** — boot `apicircle mcp` in a remote
+  session so a headless agent can drive the workspace.
+- **Workspace migration & backup** — `workspaces path` + `tar` = a clean
+  on-disk archive any other machine can pick up.
+
+## Where it fits
+
+```
+@apicircle/shared              (types + utilities)
+@apicircle/core                (request engine + auth + imports + workspace I/O)
+@apicircle/mock-server-core    (mock-server engine)
+@apicircle/mcp-server          (MCP host + tool catalog)
+└── @apicircle/cli             ◀── you are here
+```
+
+Every subcommand is a thin wrapper around one of the sister packages — same
+behaviour as the desktop app, same on-disk format. An edit made by the CLI
+is visible to the desktop app on the next read, and vice versa.
+
+## Stability
+
+Each subcommand is exercised by both unit tests and Playwright-driven E2E
+suites; the same engine runs in **1,900+ tests** across the wider Studio
+codebase. Exit codes and JSON output shapes are part of the contract — gates
+that pass today will keep passing as long as the major version doesn't change.
 
 ## License