# @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+**.

## 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
```

Examples:

```bash
# 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
```

Then discover and inspect commands as structured JSON:

```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
```

## Exit codes

`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 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).