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:

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.

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

Authenticate

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

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

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:

# 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

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