@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 or suparse process --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. When -o is omitted, the API-provided filename is used.
suparse process path/to/invoice.pdf --format xlsx

# 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

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
suparse process --folder path/to/receipts/ --format csv
suparse process --folder path/to/receipts/ --format xlsx -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

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

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, using the API filename when -o is omitted | | 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.

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 | --template-id | Template ID to use (default: auto-detect) | | 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 | | 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