@wevion/cli 1.0.2 → 1.0.3

package/README.md

@@ -1,46 +1,119 @@
-# @wevion/cli — Wevion CLI
+# @wevion/cli
 
-Generic, spec-driven command-line interface for the Wevion API. Every command
-is derived at runtime from the public OpenAPI spec — no generated code. CI
-refreshes the bundled `openapi.json` snapshot on every production release.
-The CLI exposes operations that the public spec marks as `apiKeyAuth`.
+Command-line access to the [Wevion](https://wevion.ai) API. Manage ad accounts,
+campaigns, insights, creatives and everything else the API exposes — straight
+from your terminal or a script. Every API-key-auth endpoint in the public spec is
+a command, and successful responses come back as JSON on stdout, so it's easy to
+pipe into `jq` or a script.
+
+Requires **Node.js 22+**.
 
 ## Install
 
 ```bash
-npm i -g @wevion/cli   # or: npx @wevion/cli list
+npm install -g @wevion/cli
+# or run without installing:
+npx @wevion/cli list
+```
+
+## Authenticate
+
+You need a Wevion **API key** (create one in the Wevion app under
+Settings → API keys). Then log in once:
+
+```bash
+wevion login            # prompts for the key and stores it securely
+```
+
+The key is saved under `$XDG_CONFIG_HOME/wevion/config.json` or
+`~/.config/wevion/config.json` (on Windows: `%APPDATA%\Wevion\config.json`;
+readable only by you). In CI or scripts, skip the prompt with an env var instead:
+
+```bash
+export WEVION_API_KEY=sk_live_xxx
+```
+
+Log out (delete the stored key) with `wevion logout`.
+
+## Usage
+
+```bash
+wevion <command> [--flag value ...]
+```
+
+Discover what's available:
+
+```bash
+wevion list                 # all commands, grouped by area (ad-accounts, campaigns, …)
+wevion help <command>       # flags, required params and the underlying endpoint
 ```
 
-## Use
+Examples:
 
 ```bash
-wevion login                         # prompts for the API key, saves it
-printf '%s' "$WEVION_API_KEY" | wevion login  # non-interactive; avoids shell history
-wevion logout                        # forget the saved key
-wevion list                          # list all commands, grouped by tag
-wevion help <command>                # show a command's flags
+# List your ad accounts (paginated), filtered by name
 wevion get-api-v1-ad-accounts --limit 10 --search brand
+
+# Send a request body with individual flags…
 wevion post-api-v1-ad-accounts-assign-all --connected true
+
+# …or pass the whole JSON body at once
 wevion post-api-v1-ad-accounts-assign-all --json '{"connected":true}'
+
+# Pipe JSON output into jq
+wevion get-api-v1-ad-accounts --limit 50 | jq '.data[].name'
+```
+
+Each command mirrors one API endpoint: path, query and supported header
+parameters become `--flags` using their exact OpenAPI names, and request-body
+fields are `--flags` too (use `--json '<raw>'` to send a body verbatim).
+`wevion help <command>` shows exactly which are required.
+
+## For LLMs & agents
+
+Driving the CLI from an agent (e.g. Claude Code) with no prior Wevion knowledge?
+Start with one command — a self-contained primer covering auth, how commands map
+to endpoints, parameter rules, and the output/exit-code contract:
+
+```bash
+wevion agent
 ```
 
-Credentials & base URL are resolved in this order:
+Then discover and inspect commands as structured JSON:
 
-- API key: `WEVION_API_KEY` env → `wevion login` config (`~/.config/wevion/config.json`).
-- Base URL: `--base-url` → `WEVION_BASE_URL` env → config → default `https://api.wevion.ai`
-  (stage: `https://api-stage.wevion.ai`).
+```bash
+wevion list --json              # every command: command, method, path, params, body
+wevion help <command> --json    # one command's exact parameter/body schema
+```
+
+## Configuration
+
+Resolved in this order (first wins):
+
+| Setting  | Sources                                                               |
+| -------- | --------------------------------------------------------------------- |
+| API key  | `WEVION_API_KEY` env → stored login (`wevion login`)                  |
+| Base URL | `--base-url` → `WEVION_BASE_URL` env → stored login config → default `https://api.wevion.ai` |
+
+To target staging, point the base URL at `https://api-stage.wevion.ai`:
+
+```bash
+wevion --base-url https://api-stage.wevion.ai get-api-v1-ad-accounts
+# or: export WEVION_BASE_URL=https://api-stage.wevion.ai
+```
 
-## Release
+## Exit codes
 
-The `publish-cli` job in `.github/workflows/deploy.yml` runs on every push to
-`main` that touches `apps/backend/**` or `packages/cli/**`. It regenerates the
-snapshot from the released source (`dump:openapi`), so the published CLI always
-matches the API at that commit, then `npm publish`es.
+`0` on success, `1` on an API/network/runtime error (HTTP errors print the
+request line and response body to stderr),
+`2` on a usage error (unknown command, missing required flag, no API key),
+`3` when the CLI is too old for the API — run `npm i -g @wevion/cli@latest`.
 
-Version: `MAJOR.MINOR` comes from this `package.json` (human-owned); the patch
-is the GitHub Actions run number, so every release is unique and monotonic
-(e.g. `1.0.523`). Bump the minor here when there's a meaningful change.
+---
 
-Requires the `NPM_TOKEN` repository secret (automation token with publish
-rights for the `@wevion` scope). If the bundled snapshot is ever absent the CLI
-falls back to fetching `${baseUrl}/docs/json`.
+The command set is derived from the Wevion API's **live** OpenAPI spec and
+cached briefly. Offline or non-OK spec fetches fall back to the last valid cache
+or bundled snapshot, so commands normally track the current API while still
+working without the network. The CLI checks npm for a newer version and prints an
+upgrade hint when one exists — set `NO_UPDATE_NOTIFIER=1` to silence it. Full
+endpoint details: [api.wevion.ai/docs](https://api.wevion.ai/docs).