@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

Suparse can run as a local MCP stdio server for clients such as Claude Code and Codex. MCP tools use your local API key, read local document paths, and call the Suparse API through the SDK.

Claude Code:

claude mcp add --transport stdio --env SUPARSE_API_KEY=your_api_key suparse -- suparse mcp

Codex:

[mcp_servers.suparse]
command = "suparse"
args = ["mcp"]

[mcp_servers.suparse.env]
SUPARSE_API_KEY = "your_api_key"

The extract_file and extract_folder MCP tools perform the full flow in one call: upload, poll, fetch JSON results, and optionally clean up server documents.

You can also run the dedicated MCP package without installing the CLI:

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)

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