# cowl — the ContextOwl CLI

`cowl` wraps the whole REST API in a single static binary: every endpoint is a command, authenticated with the same `cowl_pat_` agent key. Human-readable tables by default, raw JSON with `--json` for scripts.

## Install

On Linux or macOS, install the latest verified release to `~/.local/bin`:

```bash:install.sh
installer="$(mktemp)"
curl -fsSL https://github.com/ContextOwl/cowl/releases/latest/download/install.sh -o "$installer"
sh "$installer"
rm "$installer"
export PATH="$HOME/.local/bin:$PATH"
cowl version
```

The installer selects the right amd64 or arm64 archive and verifies it against `SHA256SUMS`. Set `COWL_INSTALL_DIR` to install somewhere else. Windows archives are available from [ContextOwl/cowl releases](https://github.com/ContextOwl/cowl/releases).

Or install from source with `go install github.com/ContextOwl/cowl/cmd/cowl@latest`.

## Authenticate

Create an agent key in **Admin > Settings > API**, then:

```bash:login.sh
cowl auth login          # prompts for the key (input hidden), verifies it, stores it 0600
cowl auth status         # shows base URL, key prefix, and whether the key is valid
```

Scripts and CI can skip the config file entirely: `COWL_PAT` (or `CONTEXTOWL_PAT`) takes precedence, together with `COWL_BASE_URL` and `COWL_WORKSPACE`. A workspace-bound key needs no `-w` at all — `-` (the default) means "my bound workspace".

## Work with content

```bash:tour.sh
cowl workspaces list
cowl search "agent keys" -w platform
cowl articles list -w platform
cowl articles get mcp -w platform > mcp.md          # markdown straight to a file
cowl articles create --title "Release Notes" --file notes.md -w platform
cowl articles update release-notes --status STABLE -w platform
cowl articles update release-notes --visibility internal -w platform
cowl uploads image architecture.png -w platform
cowl changelog create --title "v2 ships" --file v2.md --tags feature --status published
cowl proposals create --slug getting-started --file fix.md --note "typo sweep"
cowl memory write conventions/errors.md --body "always return the error envelope" --kind reference
```

Landing pages, the OpenAPI ingest feature, and shared workspace memory have full command groups too — run `cowl help` for the map. Destructive commands (`workspaces delete`, `changelog delete`, `openapi detach`, `memory delete`) prompt for confirmation, or take `--yes` in scripts.

## Scripting

`--json` prints the raw API response, so cowl composes with jq:

```bash:scripting.sh
# slugs of every draft
cowl articles list --json | jq -r '.[] | select(.status=="DRAFT") | .slug'

# anything the CLI has no verb for yet: the escape hatch
cowl api GET "workspaces/platform/search" --query q=sso --query semantic=true
```

Errors come back as `cowl: <code>: <message>` on stderr with exit code 1 (2 for usage mistakes), and 429s are retried once honoring `Retry-After`.

## Completions

```bash:completions.sh
eval "$(cowl completion bash)"                                # bash
cowl completion zsh > "${fpath[1]}/_cowl"                     # zsh
cowl completion fish > ~/.config/fish/completions/cowl.fish   # fish
```