Powder CLI

Upload financial statements and extract structured data directly from your terminal.

The Powder CLI handles document uploads, processing status tracking, and data retrieval for the Powder platform. Built for automation — every command supports structured JSON output and non-interactive operation, so you can compose commands into scripts and pipelines without human intervention.

Installation

pip install powder-cli

Requires Python 3.10+.

Authentication

# Recommended: environment variable
export POWDER_API_TOKEN="your-token-here"

# Interactive setup (saves to ~/.config/powder/config.json)
powder configure

# Remove stored credentials
powder configure --clear

The CLI checks for credentials in this order:

1. POWDER_API_TOKEN environment variable
2. ~/.config/powder/config.json (created by powder configure)

To get an API token, contact [email protected].

When configuring interactively, the CLI validates your key against the Powder API before saving. If the key is rejected, it is not stored. Credentials are saved with restricted file permissions (600).

Command Reference

Upload

Upload a financial statement for processing.

# Upload a brokerage statement (default type)
powder upload statement.pdf

# Specify statement type and portfolio
powder upload holdings.xlsx --type brokerage --portfolio 42

Output:

✓ Uploaded statement.pdf
  ID:          12345
  Status:      processing
  Portfolio:   67890

The returned upload ID is used with all subsequent commands.

Local Validation

Files are validated before upload:

• Must exist and be readable
• Must have a supported extension
• Must not be empty
• Must be under 50 MB

The API performs additional server-side validation after upload (password-protected PDFs, corrupt files, invalid formats) and returns descriptive error messages.

Status

Check processing status or wait for completion.

# One-time check
powder status 12345

# Poll until processing completes (prints dots as progress)
powder status 12345 --watch

# Custom timeout (default: 600s)
powder status 12345 --watch --timeout 300

Terminal statuses: done, failed, error, deleted, closed.

Non-terminal statuses: processing, in_review.

Output:

Status: done
  Portfolio: 67890

If processing fails:

Status: closed
  Error:     CORRUPT_PDF — PDF file is corrupt or damaged.
  Closed at: 2026-03-15T10:30:00Z

Data

Retrieve extracted data from a processed upload.

# JSON output (default)
powder data 12345

# Formatted table
powder data 12345 --format table

# Paginate through results
powder data 12345 --format table --page 2

Table mode renders ownerships or transactions as rich formatted tables. Falls back to JSON if the data structure is too complex for tabular display.

Results are paginated at 100 items per page:

Showing page 1 of 5 (432 total items). Use --page 2 to see more.

Configure

Manage API credentials.

# Set API key (interactive prompt)
powder configure

# Remove stored credentials
powder configure --clear

Supported File Types

Maximum file size: 50 MB

Global Flags

These flags apply to all commands and must appear before the command name.

powder --json upload statement.pdf
powder --json status 12345
powder --json data 12345

Usage

End-to-End Workflow

# 1. Set your API token
export POWDER_API_TOKEN="your-token-here"

# 2. Upload
powder upload quarterly_statement.pdf --type brokerage --portfolio 1

# 3. Wait for processing
powder status 12345 --watch

# 4. Retrieve extracted data
powder data 12345 --format table

Scripting with JSON Output

Combine --json with tools like jq for automation pipelines:

# Upload and capture the ID
UPLOAD_ID=$(powder --json upload statement.pdf | jq -r '.id')

# Wait for processing
powder --json status "$UPLOAD_ID" --watch

# Extract specific fields
powder --json data "$UPLOAD_ID" | jq '.data.ownerships[] | {ticker, value: .statement_asset_value}'

Error Handling

The CLI returns clear, actionable error messages. With --json, errors are structured:

{
  "error": "File not found: missing.pdf"
}

{
  "error": "[401] Authentication failed",
  "status_code": 401
}