# Pozy CLI

The Pozy command line tool is not published yet. From a terminal, a script or CI, use curl against the REST API, or connect your assistant to the MCP server.

The `pozy` command line tool is not published yet, so there is nothing to install. The supported ways to use Pozy from a terminal, a script or a CI job today are the REST API with `curl`, and the [MCP server](https://pozy.ai/docs/mcp) at `https://mcp.pozy.ai/mcp` for assistants that run in your terminal, such as Claude Code or Codex.

> **Do not install packages named after Pozy:**
> 
> No Pozy package is published on npm or any other registry today. If you find one that claims to be the Pozy CLI, do not install it, and tell us at support@pozy.ai.

## Set up your key

Create a key in the dashboard under **Developers → API keys** and put it in the environment. For CI, store it as a secret and expose it as `POZY_API_KEY`. Give automation its own key, so you can revoke it without affecting anyone else. A [read-only key](https://pozy.ai/docs/getting-started/authentication) is enough for reporting jobs.

```bash Terminal
export POZY_API_KEY="pz_live_..."
```

Check that it works:

```bash Terminal
curl -s https://api.pozy.ai/v1/auth/verify \
  -H "Authorization: Bearer $POZY_API_KEY" | jq
```

## Everyday jobs with curl

Every response is JSON, so the output pipes straight into `jq`.

```bash
curl -s "https://api.pozy.ai/v1/accounts?platform=instagram" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  | jq -r '.accounts[] | "\(.username)\t\(._id)"'
```

```bash
curl -s -X POST https://api.pozy.ai/v1/posts \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-week-01" \
  -d '{
    "content": "Doors open at 9.",
    "platforms": [{ "platform": "linkedin", "accountId": "6720f41a8d3be96c1e5a02f7" }],
    "scheduledFor": "2026-11-03T09:00:00",
    "timezone": "Europe/Madrid"
  }' | jq '.post | {_id, status}'
```

```bash
curl -s "https://api.pozy.ai/v1/posts?status=scheduled&dateFrom=2026-11-01&dateTo=2026-11-07" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  | jq -r '.posts[] | "\(.scheduledFor)\t\(.content[0:40])"'
```

```bash
UPLOAD=$(curl -s -X POST https://api.pozy.ai/v1/media/presign \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"filename\": \"launch.mp4\", \"contentType\": \"video/mp4\", \"size\": $(wc -c < launch.mp4) }")

curl -s -X PUT "$(echo "$UPLOAD" | jq -r .uploadUrl)" \
  -H "Content-Type: video/mp4" --data-binary @launch.mp4

echo "$UPLOAD" | jq -r .publicUrl   # use this URL in mediaItems
```

The upload URL takes the bytes directly, without your API key. [Media uploads](https://pozy.ai/docs/publishing/media) has the size and format rules for each platform.

## Every other endpoint

The [API reference](https://pozy.ai/docs/api) lists every endpoint with a cURL example you can paste into a terminal. Each one has an `operationId`, such as `createPost`, which is also the name the [MCP server](https://pozy.ai/docs/mcp) uses.

## Errors in scripts

Add `--fail-with-body` (curl 7.76 or later) to make `curl` exit with a non-zero code on an HTTP error while still printing the JSON body, so a script can stop and show what went wrong:

```bash Terminal
if ! out=$(curl -s --fail-with-body "https://api.pozy.ai/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $POZY_API_KEY"); then
  echo "Lookup failed: $(echo "$out" | jq -r .error)"
  exit 1
fi
```

The error body always has `error`, `type` and `code` ([errors](https://pozy.ai/docs/getting-started/errors)). A `429` means the workspace hit its [rate limit](https://pozy.ai/docs/getting-started/rate-limits): wait for the number of seconds in the `Retry-After` header before you try again.

## Related

- [Quickstart](https://pozy.ai/docs/getting-started/quickstart): An API key, a connected account and a first post in ten minutes.
- [MCP server](https://pozy.ai/docs/mcp): Pozy inside Claude Code, Codex, Cursor and other assistants.
- [OpenAPI spec](https://pozy.ai/docs/sdks/openapi): Generate a client in any language.