# CLI reference

> Part of the Cowliss docs. Markdown for every page: append `index.md` to its URL. Site map: /llms.txt

`Cowliss` is the admin CLI: a thin client of the dashboard API with full parity, so anything the dashboard does, the CLI does, through the same typed endpoints.

```sh
cow login                 # browser flow; caches a session for this API
cow login --token <jwt>   # or paste a Clerk session token (headless)
cow whoami                # subject, org, role, expiry of the cached token
```

Global flags, available on every command:

- `--api <url>`: API base URL; overrides env and `cow.json`. Precedence: flag → `COW_API_URL` → `apiUrl` in `cow.json` → `https://api.cowliss.com`. It must be a full `http://` or `https://` address. It also picks the login: `cow login` keeps one session per API URL, and a command uses the one for the API it talks to.
- `--json`: force compact single-line JSON output (automatic when stdout is not a TTY, i.e. in pipes and scripts).
- `--config <file>`: the config file to read instead of `cow.json`. Precedence: flag → `COW_CONFIG` → `cow.json`. Use it to keep a second config beside the committed one, so the same checkout can push to your own API without editing the file every time.

Conventions worth knowing once:

- Every command prints the API's **response envelope** as JSON: `{ data }` on success, `{ error: { code, message } }` on failure, with a non-zero exit code on failure.
- JSON-valued flags accept `-` to read the document from stdin: `cow segments preview --app-id app_web --definition - < signups.json`.
- List commands take `--cursor` and `--limit` and print `meta.nextCursor` for the next page.
- `cow add blueprint` and `cow test` are **local**: they hit no API and need no login. `cow init` is local apart from one best-effort read of the organization's apps, to write the `appId` the repo pushes to; it shrugs and leaves the field empty if it cannot. Everything else needs a session or a pipeline key.
- The repo commands (`init`, `plan`, `push`, `status`, `enable`, `disable`, `pull`, `test`, `add blueprint`) act on the tree in the current directory, and on the app its `cow.json` names. See [Your repo](/guides/repo/).

The command pages in this section are generated by walking the CLI's command tree: names, arguments, options, and descriptions come from the definitions themselves, so a changed command changes the docs on the next `pnpm -F cowliss-docs generate`. The sidebar lists every group.