POMA AI ⬣ Docs

Appearance

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. For the complete command surface and implementation notes, see poma-cli on GitHub.

Core command groups ​

AreaCommandsPurpose
healthpoma healthCheck whether the API is reachable
accountregister-email, verify-email, me, api-key, my-projects, my-usageBootstrap auth and inspect the current account
jobsingest, ingest-sync, status, status-stream, download, deleteSubmit work, follow progress, fetch the archive, and clean up

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, 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 JWT. The exceptions are:

  • poma health
  • poma account register-email
  • poma account verify-email

From the app ​

Sign in at app.poma-ai.com and copy your API key.

From the CLI ​

bash
poma account register-email --email you@example.com
poma account verify-email --email you@example.com --code '<code-from-email>'

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

bash
poma account api-key

Set the environment variable ​

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

bash
export POMA_API_TOKEN="your-api-key"
powershell
setx POMA_API_TOKEN "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:

FlagDefaultPurpose
--base-urlhttps://api.poma-ai.com/v2REST API base URL
--status-base-urlhttps://api.poma-ai.com/status/v1Status / SSE base URL
--tokennoneJWT for authenticated requests
--jsonnoneInline JSON ({...}) or a .json file under the current working directory

Token precedence is:

  1. Explicit --token
  2. token from --json
  3. POMA_API_TOKEN

--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 jobs ingest-sync --file document.pdf --output result.poma

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

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

Add --eco if you want the eco ingest route.

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

Step by step ​

  1. Submit a job:

    bash
    poma jobs ingest --file document.pdf

    Or from stdin:

    bash
    poma jobs 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.

Discovering commands ​

Use Cobra help to explore the full surface:

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

See also ​