@wevion/cli 1.0.2380 → 1.0.2381

package/README.md

@@ -1,119 +1,46 @@
-# @wevion/cli
+# @wevion/cli — Wevion CLI
 
-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+**.
+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`.
 
 ## Install
 
 ```bash
-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
+npm i -g @wevion/cli   # or: npx @wevion/cli list
 ```
 
-Examples:
+## Use
 
 ```bash
-# List your ad accounts (paginated), filtered by name
+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
 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
 ```
 
-Then discover and inspect commands as structured JSON:
+Credentials & base URL are resolved in this order:
 
-```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
-```
+- 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`).
 
-## Exit codes
+## Release
 
-`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`.
+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.
 
----
+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.
 
-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).
+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`.