@marginfront/sdk 0.0.1 → 0.1.1

package/README.md

@@ -305,6 +305,91 @@ console.log(`Total Requests: ${stats.requestCount}`);
 console.log(`Success Rate: ${(stats.successRate * 100).toFixed(2)}%`);
 ```
 
+
+## CLI (Testing Tool)
+
+The SDK ships with a lightweight CLI (`mf`) for testing your integration without writing code.
+
+> **Note:** The CLI is a testing tool only. It has no effect on the SDK when used as a library in your application.
+
+### Install globally
+
+```bash
+npm install -g @marginfront/sdk
+```
+
+Then run commands from anywhere:
+
+```bash
+mf verify
+mf track-event --customer-id customer-1 --agent-id <uuid> --signal CALL_MINUTES --quantity 10
+```
+
+### Commands
+
+#### `mf verify`
+
+Verifies your API key and returns organization details.
+
+```bash
+mf verify [options]
+
+Options:
+  --api-key <key>    API key (mf_sk_* or mf_pk_*)
+  --base-url <url>   API base URL (default: https://api.revmax.ai/v1)
+  --debug            Enable debug output
+```
+
+#### `mf track-event`
+
+Sends a single usage event to the API.
+
+```bash
+mf track-event [options]
+
+Options:
+  --api-key <key>      API key (mf_sk_*)
+  --base-url <url>     API base URL (default: https://api.revmax.ai/v1)
+  --customer-id <id>   Customer external ID
+  --agent-id <id>      Agent UUID
+  --signal <name>      Signal name (e.g. CALL_MINUTES)
+  --quantity <number>  Quantity to record (default: 1)
+  --metadata <json>    Optional metadata as a JSON string
+  --debug              Enable debug output
+```
+
+### Default values via `.env.marginfront.cli`
+
+To avoid repeating flags, create a `.env.marginfront.cli` file in the directory where you run the CLI. Any value set here is used as a default and can be overridden by passing the flag directly.
+
+```env
+# ⚠️  FOR TESTING ONLY
+# This file is NOT used when the SDK is imported as a library.
+# It only applies when running the mf CLI.
+
+MF_API_KEY=mf_sk_your_key_here
+MF_BASE_URL=http://localhost:4000/v1
+MF_AGENT_ID=your-agent-uuid
+MF_CUSTOMER_ID=customer-1
+MF_SIGNAL=CALL_MINUTES
+MF_QUANTITY=10
+MF_DEBUG=false
+```
+
+**Priority:** CLI flags > `.env.marginfront.cli` > built-in defaults
+
+| CLI Flag        | `.env` Key        |
+|-----------------|-------------------|
+| `--api-key`     | `MF_API_KEY`      |
+| `--base-url`    | `MF_BASE_URL`     |
+| `--customer-id` | `MF_CUSTOMER_ID`  |
+| `--agent-id`    | `MF_AGENT_ID`     |
+| `--signal`      | `MF_SIGNAL`       |
+| `--quantity`    | `MF_QUANTITY`     |
+| `--debug`       | `MF_DEBUG`        |
+
+Add `.env.marginfront.cli` to your `.gitignore` to avoid committing test credentials.
+
 ## License
 
 MIT License. See [LICENSE](./LICENSE) for details.