@everfur/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Everfur Health, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,114 @@
+# Everfur CLI
+
+Plan, verify, and diagnose an [Everfur](https://everfur.com) pet-health integration from the terminal,
+and serve the same tools to your coding agent over MCP.
+
+Everfur lets partner apps embed veterinary chat, health records, and pet-state surfaces via
+`@everfur/sdk` (React Native). This CLI is the integration companion: it reads your project, plans the
+integration, exercises the live wire, and explains what it finds.
+
+## The fastest path: let your agent do it
+
+The Everfur MCP server ships with this package (and standalone as `@everfur/mcp`). Add it to your
+agent's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "everfur": {
+      "command": "npx",
+      "args": ["-y", "@everfur/mcp"],
+      "env": {
+        "EVERFUR_API_BASE_URL": "https://api.everfur.com/api/v1",
+        "EVERFUR_PARTNER_KEY": "pk_live_your_key"
+      }
+    }
+  }
+}
+```
+
+Then ask your agent to add Everfur to your app. The `everfur_plan_integration` tool reads your project,
+refuses to guess the facts only you can answer (which capabilities, which identity mode), and returns a
+plan whose steps include the complete integration file, ready to write.
+
+## Install the CLI
+
+```bash
+npm install -g @everfur/cli
+```
+
+To run it once without installing, name the command explicitly:
+
+```bash
+npx -y -p @everfur/cli everfur plan
+```
+
+Plain `npx @everfur/cli` does not work, and the error it gives ("could not determine executable to
+run") does not explain why: this package ships two binaries, `everfur` and `everfur-mcp`, and npx only
+picks a binary on its own when there is exactly one, or when one is named after the package. `-p` names
+the package and the word after it names the binary.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `everfur plan` | Produce an integration plan for the project in the current directory. |
+| `everfur verify` | Exercise the wire: mint a session, read the verdict, assert it is not empty. |
+| `everfur diagnose` | Explain why each capability is or is not available to this caller. |
+| `everfur explain-error` | Explain an API error code: cause, retryability, and next action. |
+| `everfur contract validate` | Validate a contract-public projection: envelope shape, then digest. |
+| `everfur sandbox create` | Provision a partner secret key (Everfur-internal; requires an admin token). |
+
+`--json` on any command emits a machine-readable document on stdout, which is what you want in CI.
+
+## Exit codes
+
+CI is invited to branch on these. An existing code never changes meaning.
+
+| Code | Name | Meaning |
+|---|---|---|
+| `0` | OK | The command produced a complete answer. |
+| `1` | INTERNAL_ERROR | A bug in the CLI, or an unreadable filesystem. |
+| `2` | USAGE_ERROR | Malformed invocation: unknown command or flag, missing flag value. |
+| `3` | UNDERSPECIFIED | The CLI refused to guess. Required facts were missing; supply them and retry. |
+| `4` | INVALID_CONTRACT | A named artifact was missing, unparseable, or failed schema validation. |
+| `5` | DIGEST_MISMATCH | A loaded artifact was well shaped but its digest did not match its content. |
+| `6` | REMOTE_FAILURE | The API could not be reached, timed out, or answered with a typed error. |
+| `7` | VERIFICATION_FAILED | `verify` ran and at least one hard assertion failed. |
+| `8` | SECRET_UNCLAIMABLE | `sandbox create` minted a key but no claim flow exists to hand it over safely. |
+| `9` | BLOCKED | Everything you asked for is blocked by the contract; nothing can be built today. |
+
+---
+
+## What this release does NOT do
+
+`everfur login` and `everfur test message` are unbuilt. They are absent rather than stubbed on
+purpose: a stub that pretends teaches you to distrust the tool. Sending a test message is available
+today through the MCP server's `everfur_send_test_message` tool, which refuses to run against anything
+but a sandbox tenant.
+
+## Credentials
+
+Configuration comes from environment variables only. No `.env` file is read.
+No command prints, logs, or writes a credential; two commands DO handle them in memory: `everfur sandbox create` mints a partner
+secret (and requires `EVERFUR_ADMIN_TOKEN`), and `everfur verify` reads your keys to exercise the wire.
+
+| Variable | Used for |
+|---|---|
+| `EVERFUR_API_BASE_URL` | Everything that touches the network. No default host. |
+| `EVERFUR_PARTNER_KEY` | Your publishable key (`pk_live_...`). Identifies your tenant. |
+| `EVERFUR_PARTNER_SECRET_KEY` | Session minting, server side only. Never ship it in an app. |
+| `EVERFUR_ADMIN_TOKEN` | Everfur-internal administration. Partners do not need this. |
+
+**Getting keys:** Everfur keys are currently provisioned by the Everfur team during partner onboarding;
+there is no self-serve signup yet. Contact [support@everfur.com](mailto:support@everfur.com) to get set
+up. The publishable key is designed to ship inside your app; the secret key is not.
+
+## Documentation
+
+The full integration guide, API reference, error catalog, and testing guide ship with the SDK:
+[`@everfur/sdk` docs](https://github.com/Everfur-Health/everfur-sdk-rn/tree/main/docs/partner-integration).
+
+## License
+
+MIT