@suparse/cli

Official CLI for the Suparse Document Processing API.

Suparse is an AI-powered document processing API for extracting structured data from any document type, including invoices, receipts, bank statements, purchase orders and many more.

Requirements

• Node.js 20+
• A Suparse API key

Installation

Install the CLI globally:

npm install -g @suparse/cli

Or run the CLI without a global install:

npx @suparse/cli process invoice.pdf -o results.json

Authentication

You'll need an API key to use the CLI. To obtain one:

1. Sign in at suparse.com
2. Go to the API Keys tab
3. Enter a key name and click Generate New Key
4. Copy the key value. It will be shown only once.

Set it as an environment variable:

export SUPARSE_API_KEY="your_api_key_here"

You can also pass it directly with --api-key.

Quick Start

export SUPARSE_API_KEY="your_api_key_here"
suparse process invoice.pdf -o results.json

The CLI will auto-upload, poll, and download the resulting JSON. JSON is the default export format.

CLI Usage

Run suparse --help, suparse process --help, or suparse export --help for full usage information.

Process a Document

export SUPARSE_API_KEY="your_api_key_here"

# Auto-detect template
suparse process path/to/invoice.pdf -o results.json

# Export as XLSX with the flat layout. The default layout is standard.
suparse process path/to/invoice.pdf --format xlsx --xlsx-layout flat

# Export as CSV using each document's original template
suparse process path/to/invoice.pdf --format csv --export-type original

# Use a specific template without auto-splitting
suparse process path/to/invoice.pdf --template-id 276a0aa8-84bc-4491-a2e7-1ea13381790c

# Auto-split a multi-page PDF containing mixed document types
suparse process path/to/merged.pdf --with-split

# Use a specific template with auto-splitting
suparse process path/to/invoice.pdf --template-id 276a0aa8-84bc-4491-a2e7-1ea13381790c --with-split

# Process and auto-delete documents from the server after download
suparse process path/to/invoice.pdf --cleanup

# Assign uploads to a remote folder
suparse process path/to/invoice.pdf --folder-id <folder-id>

# Prompt without echoing for an encrypted PDF password
suparse process path/to/encrypted.pdf --prompt-pdf-password

Export Existing Documents

Export one or more processed documents by ID:

# Export a document to XLSX with the flat layout
suparse export <document-id> --format xlsx --xlsx-layout flat

# Export several documents using the default standard XLSX layout
suparse export <document-id-1> <document-id-2> --format xlsx

When -o is omitted, file exports use the filename returned by the API. The --xlsx-layout option accepts standard or flat and defaults to standard.

Process a Folder

Process all supported files (.pdf, .jpg, .jpeg, .png, .heic, .heif) in a folder. Files are uploaded and polled individually, then results are exported together. JSON exports are written to a single JSON file; CSV and XLSX exports may be saved as a direct file or ZIP depending on the API response.

# Process all supported files in a folder
suparse process --folder path/to/receipts/

# Output to a specific file (default: {folder_name}_results.json)
suparse process --folder path/to/receipts/ -o all_results.json

# Export a folder as CSV or XLSX. XLSX layout defaults to standard.
suparse process --folder path/to/receipts/ --format csv
suparse process --folder path/to/receipts/ --format xlsx --xlsx-layout flat -o ./exports

# Export to Google Sheets. This requires a working Google integration.
suparse process --folder path/to/receipts/ --format google_sheets

# Process a folder with a specific template
suparse process --folder path/to/receipts/ --template-id 276a0aa8-84bc-4491-a2e7-1ea13381790c

# Process a folder with auto-splitting enabled
suparse process --folder path/to/receipts/ --with-split

# Process a folder and auto-delete documents from the server after download
suparse process --folder path/to/receipts/ --cleanup

# Apply one remote folder and prompted PDF password to every file in the batch
suparse process --folder path/to/receipts/ \
  --folder-id <folder-id> --prompt-pdf-password

--prompt-pdf-password requires an interactive TTY, never echoes the password, and restores terminal state when the prompt exits. There is intentionally no plaintext --pdf-password option. The same password and folder ID are forwarded to every file in a local-folder batch.

Quick schema creation

Start automatic schema creation for one document:

suparse quick-create invoice.pdf
suparse quick-create invoice.pdf --wait --format json
suparse quick-create encrypted.pdf --prompt-pdf-password --folder-id <folder-id>

Inspect one status without polling:

suparse quick-create-status <run-id>
suparse quick-create-status <run-id> --format json

Quick-create also accepts --upload-batch-id and --source-upload-id for advanced replay workflows. Upload-batch creation is outside the endpoint set currently exposed by this SDK, so those IDs must come from another workflow. JSON output preserves the complete wire result. Human output includes the run ID, status/stage, path, template IDs, progress counts, and retryability when available.

Multiple-document completions additionally list every saved document with its ordinal, page range, template ID, and template group ID, followed by each failed document's page range, error code, and retryability.

Exit codes

quick-create --wait and quick-create-status use the terminal result to pick the process exit code so scripts can branch without parsing output:

| Terminal status | Exit code | | ------------------------ | --------- | | completed | 0 | | completed_with_errors | 1 | | failed | 1 |

quick-create without --wait exits 0 after the run is accepted.

Delete Documents

# Delete one or more documents by ID (prompts for confirmation)
suparse delete <document_id>
suparse delete <id1> <id2> <id3>

# Skip confirmation prompt
suparse delete <id1> <id2> -y

Deleting a parent document automatically deletes all its child documents server-side.

List Available Templates

Templates define how a document type (invoice, receipt, bank statement, etc.) is parsed. Before processing a document, check which templates are already assigned to your account:

# List templates assigned to your account (table format)
suparse templates

# List templates in JSON format
suparse templates --format json

# Include all system templates
suparse templates --include-system

# Request full template records (summary remains the default)
suparse templates --view full --format json

The recommended way to process documents is with auto-split enabled (--with-split), which handles both single-type and mixed document types automatically:

suparse process path/to/documents.pdf --with-split -o results.json

If you consistently process one document type, look up the template ID and pass it directly:

1. Run suparse templates to see templates assigned to your account.

2. Use the matching template ID:

   suparse process invoice.pdf --template-id <id> -o results.json

3. If no template matches, run suparse templates --include-system to browse all system templates. Assign one to your account via the Suparse UI.

4. If no system template fits, create a custom template using the template creator in the Suparse UI.

Export Formats

The process command supports these export formats:

| Format | Output behavior | | --------------- | ------------------------------------------------------------------------------- | | json | Default. Writes the task-oriented JSON export to {file_stem}_results.json or {folder_name}_results.json | | csv | Saves a CSV file or ZIP archive, using the API filename when -o is omitted | | xlsx | Saves an XLSX file or ZIP archive; --xlsx-layout defaults to standard and also accepts flat | | google_sheets | Writes the Google Sheets JSON response, including spreadsheet or folder URLs |

--export-type original|unified defaults to unified and affects CSV, XLSX, and Google Sheets exports. JSON remains the default when --format is not provided.

--xlsx-layout standard|flat defaults to standard and applies only to XLSX exports. Use it with either process or export.

MCP Server

The MCP server is maintained separately in suparse/suparse-mcp and published as @suparse/mcp. Run it directly with npx:

npx -y @suparse/mcp

Configuration

The CLI reads settings from global flags, environment variables, and the config file at ~/.config/suparse/config.json.

| Variable | Default | Description | | ----------------- | -------------------------------- | ----------------------- | | SUPARSE_API_URL | https://api.suparse.com/api/v1 | API base URL | | SUPARSE_API_KEY | - | Your API key (required) | | SUPARSE_CONFIG_PATH | ~/.config/suparse/config.json | Optional config file override |

API key priority: --api-key > SUPARSE_API_KEY > ~/.config/suparse/config.json. The config file should contain an apiKey string field. API URL priority: --api-url > SUPARSE_API_URL > default.

Global Options

These options apply to all subcommands.

| Option | Description | | ----------------- | ------------------------------------------------- | | --api-url | API URL (default: from SUPARSE_API_URL env var) | | --api-key | API key (default: from env var or config file) | | -v, --verbose | Enable verbose output |

CLI Options

| Command | Option | Description | | ----------- | ------------------ | ------------------------------------------------------------------------------------------------------ | | process | --folder | Process all supported files in a folder | | process | -o, --output | Output file path, or output directory for file exports when omitted | | process | --format | Export format: json, csv, xlsx, or google_sheets (default: json) | | process | --export-type | Export mode: original or unified (default: unified) | | process | --xlsx-layout | XLSX layout: standard or flat (default: standard) | | process | --template-id | Template ID to use (default: auto-detect) | | process | --folder-id | Assign uploaded documents to a remote folder | | process | --prompt-pdf-password | Prompt securely for an encrypted-PDF password | | process | --with-split | Auto-split multi-page documents containing mixed document types | | process | --cleanup | Delete documents from server after download | | templates | --format | Output format: table or json (default: table) | | templates | --include-system | Include system templates | | templates | --view | Template response view: summary or full (default: summary) | | quick-create | --wait | Poll until quick schema creation reaches a terminal result | | quick-create | --format | Output format: human or json (default: human) | | quick-create | --folder-id | Assign the source document to a remote folder | | quick-create | --upload-batch-id | Use an existing upload batch ID (batch creation is outside this SDK) | | quick-create | --source-upload-id | Use an existing source upload ID for replay-aware creation | | quick-create | --prompt-pdf-password | Prompt securely for an encrypted-PDF password | | quick-create-status | --format | Output format: human or json (default: human) | | export | --format | Export format: json, csv, xlsx, or google_sheets (default: json) | | export | -o, --output | Output file path or directory | | export | --export-type | Export mode: original or unified (default: unified) | | export | --xlsx-layout | XLSX layout: standard or flat (default: standard) | | delete | -y, --yes | Skip confirmation prompt |

Supported Files

| Extension | MIME Type | | --------------- | ----------------- | | .pdf | application/pdf | | .jpg, .jpeg | image/jpeg | | .png | image/png | | .heic | image/heic | | .heif | image/heif |

SDK

The companion JavaScript and TypeScript SDK is published as @suparse/sdk:

npm install @suparse/sdk

import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient();
const result = await client.extract("invoice.pdf");
console.log(result.succeeded);
await client.close();

Documentation

Full API documentation is available at suparse.com/docs.

License

MIT