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

• 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.

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