POMA CLI

Problem:

"Current RAG systems chunk documents the same way a paper shredder does — fast, uniform, and completely unaware of meaning.

Tables get split in half. Headings lose their content. A sentence that only makes sense in context gets retrieved alone. The AI does its best with the fragments it receives — but when the fragments are broken, the answers are too.

Hallucinations, missed facts, and lost context aren't model problems. They're chunking problems."

Solution:

POMA AI PrimeCut.

PrimeCut understands your document's content hierarchy before chunking — preserving structural relationships, eliminating context poisoning, and producing semantically coherent chunks that make every downstream RAG component more accurate by default.

Install

You can install the poma binary in any of these ways:

Homebrew — Homebrew serves prebuilt releases from the poma-ai/poma tap:

brew tap poma-ai/poma
brew install poma

Go toolchain — requires Go 1.21 or later:

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

Put $GOPATH/bin or $GOBIN on your PATH if it is not already.

From source — clone this repository and build (Go 1.21+):

git clone https://github.com/poma-ai/poma-cli
cd poma-cli
go mod tidy
go build -o poma .

Usage

Most API calls need a JWT (see API key below). Export it or pass --token on each command.

Example: ingest a file, wait until the job finishes, then retrieve the result. Ingest is asynchronous, so you poll or stream status before fetching results.

# export POMA_API_KEY='<your-jwt>'

# Ingest and receive JSON result on stdout (no --output)
poma primecut ingest-sync --file document.pdf
# poma primecut ingest-sync --filename document.pdf < document.pdf

# Ingest and download the archive instead
poma primecut ingest-sync --file document.pdf --output result.poma

### Alternative: process each step manually

# 1. Submit a file for processing; save the job_id from the output
poma primecut ingest --file document.pdf
# Or pipe bytes: poma primecut ingest --filename document.pdf < document.pdf
# Or fetch server-side: poma primecut ingest --remote-url https://example.com/document.pdf
# Optional metadata: --label confidential --label year:1982 --meta-int-1 1644710400

# 2. Wait until the job completes (or fails)
poma job status-stream --job-id <job_id>
# Or poll: poma job status --job-id <job_id>

# 3a. When status is "done", fetch the result JSON
poma job result --job-id <job_id>

# 3b. Or download the archive
poma job download --job-id <job_id> --output result.poma

Global flags (apply to all subcommands):

• --base-url — REST API base URL (default: https://api.poma-ai.com/v3)
• --status-base-url — status / SSE base URL (default: https://api.poma-ai.com/status/v1)
• --token or env POMA_API_KEY — JWT for authenticated requests
• --json (optional) — merge options from JSON: either an inline object (must start with {) or a path to a .json file in the current working directory. Keys are snake_case (e.g. token, job_id, file, output, base_url). Explicit flags override values from --json.

Grill (RAG)

The grill command group calls the /grill/* endpoints: ingest a document, run hybrid search, and manage documents in the grill namespace.

# Ingest a local file (or use --remote-url to have the server fetch it)
poma grill ingest --file paper.pdf
poma grill ingest --remote-url https://example.com/paper.pdf \
                  --meta-tag year:1982 --meta-tag source:treasury \
                  --meta-int-1 1644710400

# Eco pipeline
poma grill ingest-eco --file paper.pdf

# Prompt-ready RAG context (default); pass --format json for ranked hits
poma grill search --query "what is the policy?" --target-tokens 6000
poma grill search-in-doc --query "summary" --doc-id paper_pdf_abc123

# Document management
poma grill docs list
poma grill docs get --doc-id paper_pdf_abc123
poma grill docs delete --doc-id paper_pdf_abc123

All grill commands accept --project-id, which is sent as the X-Project-ID header. Use it when authenticating with a login token or account API key against a project; project API keys do not need it.

API key

Register for free and try out our ingestion / chunking solution (1000 pages / 100k tokens).

Via the web app

1. Sign up at app.poma-ai.com.
2. Copy your API key from the app and set POMA_API_KEY, or pass it with --token.

Via the CLI

# 1. Start registration (no token required)
poma account register-email --email you@example.com

# 2. Complete verification with the code from email; the command prints a JWT you can use immediately
poma account verify-email --email you@example.com --code 123456
export POMA_API_KEY='<jwt-from-verify-output>'

# 3. Generate a long-lived opaque API key (recommended for ongoing use)
export POMA_API_KEY=$(poma account generate-api-key | jq -r '.api_key')

poma account generate-api-key calls POST /generateApiKey and prints {"api_key":"…"}. Use this key as POMA_API_KEY for all subsequent sessions — it is longer-lived and more suitable for automation than the short-lived verify token.