Source: http://www.poma-ai.com/docs/cli/

# POMA AI CLI

The `poma` CLI is the command-line client for the POMA AI public API. It covers the same core ingest workflow as the SDK and HTTP API, with a few shell-friendly extras like `ingest-sync` and `--json`.

These docs intentionally stay focused on the main path: install the CLI, authenticate, check health, ingest a document, watch the job, and download the resulting `.poma` archive.

For full endpoint details, use the [API docs](https://api.poma-ai.com/v3/docs). For the complete command surface and implementation notes, see [`poma-cli` on GitHub](https://github.com/poma-ai/poma-cli).

## Core command groups

| Area | Commands | Purpose |
|------|----------|---------|
| `health` | `poma health` | Check whether the API is reachable |
| `account` | `register-email`, `verify-email`, `me`, `generate-api-key`, `my-projects`, `my-usage` | Bootstrap auth and inspect the current account |
| `jobs` | `status`, `status-stream`, `download`, `delete`, `result` | Follow progress, fetch the archive, and clean up |
| `primecut` | `ingest`, `ingest-sync` | Ingest a document |

## Install

Prebuilt release archives are published for:

- Linux: `amd64`, `arm64`
- macOS: `amd64`, `arm64`
- Windows: `amd64`

Download the archive that matches your platform from the [`poma-cli` releases page](https://github.com/poma-ai/poma-cli/releases), extract it, and place `poma` or `poma.exe` on your `PATH`.

**Homebrew** (macOS):

```bash
brew tap poma-ai/poma
brew install poma
```

**Go** (macOS / Linux / Windows, Go 1.21+):

```bash
go install github.com/poma-ai/poma-cli@latest
```

Make sure `$GOBIN` or `$GOPATH/bin` is on your `PATH`.

## Authentication

Most commands need a login token or api key. The exceptions are:

- `poma health`
- `poma account register-email`
- `poma account verify-email`

### From the app

Sign in at [console.poma-ai.com](https://console.poma-ai.com), generate and copy your API key.

### From the CLI

```bash
poma account register-email --email you@example.com
res=$(poma account verify-email --email you@example.com --code '<code-from-email>')
export POMA_API_KEY=$(echo $res | jq -r '.token')
```

The token printed by `verify-email` is enough to start using authenticated commands immediately. For ongoing use, generate and fetch the long-lived `api_key`:

```bash
res=$(poma account generate-api-key)
export POMA_API_KEY=$(echo $res | jq -r '.api_key')
```

> Note: When generating an api key, the old one will instantly be invalidated.

## Set the environment variable

Use either the API key copied from the app or the `api_key` value returned by `poma account generate-api-key`.

::: code-group

```bash [macOS / Linux]
export POMA_API_KEY="your-api-key"
```

```powershell [Windows]
setx POMA_API_KEY "your-api-key"
```

:::

On Windows, open a new terminal after running `setx`.

You can also pass the token directly with `--token`, or provide it via `--json`.

## Global flags

These flags apply to every subcommand:

| Flag | Default | Purpose |
|------|---------|---------|
| `--base-url` | `https://api.poma-ai.com/v3` | REST API base URL |
| `--status-base-url` | `https://api.poma-ai.com/status/v1` | Status / SSE base URL |
| `--token` | none | JWT for authenticated requests |
| `--json` | none | Inline JSON (`{...}`) or a `.json` file under the current working directory |

Token precedence is:

1. Explicit `--token`
2. `token` from `--json`
3. `POMA_API_KEY`

`--json` only merges the core snake_case keys that map to real flags on the invoked command:

`base_url`, `status_base_url`, `token`, `email`, `username`, `company`, `code`, `file`, `job_id`, `output`

Explicit flags always override values from `--json`.

Example:

```bash
poma jobs download --json '{"job_id":"<job_id>","output":"bin/result.poma"}'
```

## Health check

Use this when you want a quick unauthenticated check against the API:

```bash
poma health
```

## Core workflow

### Fast path: ingest, wait, and download

`ingest-sync` is the easiest end-to-end workflow. It submits the job, streams status updates until a terminal state, and downloads the archive when the job finishes.

```bash
poma primecut ingest-sync --file document.pdf --output result.poma
```

You can also pipe bytes through stdin and provide the filename separately:

```bash
poma primecut ingest-sync --filename document.pdf < document.pdf --output result.poma
```

If you omit `--output`, the archive is written to `bin/<job_id>.poma`.

### Step by step

1. Submit a job:

   ```bash
   poma primecut ingest --file document.pdf
   ```

   Or from stdin:

   ```bash
   poma primecut ingest --filename document.pdf < document.pdf
   ```

   On success, `ingest` prints the job id as JSON.

2. Follow the job:

   ```bash
   poma jobs status-stream --job-id '<job_id>'
   ```

   If you only want a single status response instead of a live stream:

   ```bash
   poma jobs status --job-id '<job_id>'
   ```

3. Download the result:

   ```bash
   poma jobs download --job-id '<job_id>' --output result.poma
   ```

### Delete a job

If you no longer need a job, you can request deletion:

```bash
poma jobs delete --job-id '<job_id>'
```

## Output and path rules

The CLI keeps a few path-related behaviors intentionally narrow:

- `--json` file paths must resolve under the current working directory.
- Download outputs must also resolve under the current working directory.
- If you do not pass `--output`, downloads go to `bin/<job_id>.poma`.

The CLI downloads `.poma` archives, but it does not unpack them. If you want to inspect archive contents programmatically, use the [SDK archive docs](/sdk/concepts/results-and-archives).

## Discovering commands

Use Cobra help to explore the full surface:

```bash
poma --help
poma account --help
poma jobs --help
```

## See also

- [SDK overview](/sdk/)
- [Results and archives](/sdk/concepts/results-and-archives)
- [API docs](https://api.poma-ai.com/v2/docs)
- [Console](https://console.poma-ai.com/)