@suparse/cli

@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:

• Sign in at suparse.com
• Go to the API Keys tab
• Enter a key name and click Generate New Key
• 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.

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

# 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 to a single JSON file.

# 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

# 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:

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

• Use the matching template ID:

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

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

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

Configuration

The CLI reads settings from environment variables and global flags.

Variable	Default	Description
SUPARSE_API_URL	https://api.suparse.com/api/v1	API base URL
SUPARSE_API_KEY	-	Your API key (required)

Priority: CLI flags > environment variables > defaults.

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 SUPARSE_API_KEY env var)
-v, --verbose	Enable verbose output

CLI Options

Command	Option	Description
process	--folder	Process all supported files in a folder
process	-o, --output	Output JSON file path (default: {file_stem}_results.json, folder mode: {folder_name}_results.json)
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