PaperHero CLI

Command-line interface for PaperHero -- the document management system for letters, invoices, and contracts.

Designed for both human operators and AI agents. Fully non-interactive: all input is provided via flags or environment variables, making it ideal for automation, scripting, and integration with AI workflows.

Connect your OpenClaw, NemoClaw, Claude Code, Cline, or OpenCode to PaperHero in minutes.

Install

One-line install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/blaumedia/paperhero-cli/master/install.sh | sh

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/blaumedia/paperhero-cli/master/install.sh | sh -s -- --version v1.0.0

Install to a custom directory:

curl -fsSL https://raw.githubusercontent.com/blaumedia/paperhero-cli/master/install.sh | sh -s -- --dir ~/.local/bin

Windows (PowerShell)

# Download latest release
$arch = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }
$release = Invoke-RestMethod "https://api.github.com/repos/blaumedia/paperhero-cli/releases/latest"
$asset = $release.assets | Where-Object { $_.name -eq "paperhero_windows_${arch}.zip" }
Invoke-WebRequest $asset.browser_download_url -OutFile paperhero.zip
Expand-Archive paperhero.zip -DestinationPath "$env:LOCALAPPDATA\paperhero" -Force
Remove-Item paperhero.zip

# Add to PATH (current session)
$env:PATH += ";$env:LOCALAPPDATA\paperhero"

# Add to PATH (permanent, user-level)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:LOCALAPPDATA\paperhero", "User")

Manual download

Download the binary for your platform from the Releases page.

Platform	Architecture	Download
Linux	x86_64	paperhero_linux_amd64.tar.gz
Linux	ARM64	paperhero_linux_arm64.tar.gz
macOS	Intel	paperhero_darwin_amd64.tar.gz
macOS	Apple Silicon	paperhero_darwin_arm64.tar.gz
Windows	x86_64	paperhero_windows_amd64.zip
Windows	ARM64	paperhero_windows_arm64.zip

Linux / macOS:

tar -xzf paperhero_*.tar.gz
sudo mv paperhero /usr/local/bin/

Windows (PowerShell):

Expand-Archive paperhero_windows_amd64.zip -DestinationPath .
Move-Item paperhero.exe C:\Windows\System32\
# Or add the directory to your PATH instead

Docker

The CLI is also available as a Docker image, suitable as a base for automation pipelines.

# Run directly
docker run --rm ghcr.io/blaumedia/paperhero-cli version

# Use in automation
docker run --rm \
  -e PAPERHERO_CUSTOMER_ID=mycompany \
  -e [email protected] \
  -e PAPERHERO_PASSWORD=secret \
  ghcr.io/blaumedia/paperhero-cli login

# With E2E encryption (mount the key file into the container)
docker run --rm \
  -e PAPERHERO_CUSTOMER_ID=mycompany \
  -e [email protected] \
  -e PAPERHERO_PASSWORD=secret \
  -e PAPERHERO_KEY_FILE=/keys/e2e-key.json \
  -e PAPERHERO_KEY_PASSWORD=e2e-secret \
  -v /path/to/paperhero-e2e-key.json:/keys/e2e-key.json:ro \
  ghcr.io/blaumedia/paperhero-cli \
  document download <id> /output/doc.pdf

# As a base image for custom automation
FROM ghcr.io/blaumedia/paperhero-cli:latest
COPY my-automation.sh /usr/local/bin/
ENTRYPOINT ["my-automation.sh"]

The image is based on Alpine Linux and includes jq, curl, and bash for scripting. Available for linux/amd64 and linux/arm64.

Verify installation

paperhero --help

Quick Start

1. Login

paperhero login --customer-id mycompany --email [email protected] --password 'yourpassword'

The session is stored in ~/.config/paperhero/session.json with 0600 permissions.

2. List inbox

paperhero inbox list

3. Upload a document

paperhero inbox upload invoice.pdf

4. Import from inbox

# Use AI-generated recommendations for name, folder, tags
paperhero inbox import <inbox-item-id> --use-ai-defaults --password 'yourpassword'

5. Download and decrypt a document

paperhero document download <document-id> ./output.pdf --password 'yourpassword'

Authentication

All credentials are provided via flags or environment variables. The CLI never prompts for input.

Environment Variables

Variable	Description
PAPERHERO_CUSTOMER_ID	Customer/tenant identifier
PAPERHERO_EMAIL	User email address
PAPERHERO_PASSWORD	User password (login and decryption)
PAPERHERO_TOTP_CODE	Two-factor authentication code
PAPERHERO_TOKEN	JWT token (bypasses login)
PAPERHERO_SESSION_FILE	Custom session file path
PAPERHERO_KEY_FILE	Path to E2E encryption key file
PAPERHERO_KEY_PASSWORD	Password for E2E key file

Using environment variables

export PAPERHERO_CUSTOMER_ID=mycompany
export [email protected]
export PAPERHERO_PASSWORD=secret
paperhero login

Two-factor authentication

If 2FA is enabled on the account, provide the TOTP code during login:

paperhero login --customer-id mycompany --email [email protected] \
  --password 'secret' --totp-code 123456

If you omit --totp-code, the CLI returns a temporary token and instructions to complete the 2FA step:

# Step 1: Initiate login (returns twofactor token)
paperhero login --customer-id myco --email [email protected] --password secret

# Step 2: Complete with TOTP code
paperhero login --customer-id myco \
  --twofactor-token <token-from-step-1> --totp-code 123456

E2E Encryption

For accounts with end-to-end encryption enabled, commands that require decryption (document download, inbox import) need the E2E key file:

paperhero document download <id> ./output.pdf \
  --key-file ~/paperhero-keys.json \
  --key-password 'e2e-password'

Commands

Global Flags

Flag	Short	Description
--json	-j	Output as JSON (machine-readable)
--quiet	-q	Suppress non-essential output
--session-file		Custom session file path

paperhero login

Authenticate and store the session.

paperhero login --customer-id <id> --email <email> --password <pass>

paperhero logout

Remove the stored session.

paperhero logout

paperhero whoami

Show the current session information.

paperhero whoami
paperhero whoami --json

paperhero inbox

Manage inbox items (uploaded documents awaiting import).

# List all inbox items with AI recommendations
paperhero inbox list
paperhero inbox list --ready-only --json

# Show details of an inbox item
paperhero inbox show <id>

# Upload files to inbox
paperhero inbox upload invoice.pdf
paperhero inbox upload page1.jpg page2.jpg page3.jpg --source-tool Scanner

# Import an inbox item as a document
paperhero inbox import <id> --use-ai-defaults --password <pass>
paperhero inbox import <id> --name "Invoice" --folder-id <fid> --tags "invoice,2024" --password <pass>

# Create a new folder during import
paperhero inbox import <id> --use-ai-defaults --create-folder "Invoices/2024" --password <pass>

# Delete an inbox item
paperhero inbox delete <id>

# Re-trigger AI processing
paperhero inbox reprocess <id>

paperhero document (alias: doc)

Manage documents.

# List documents in a folder
paperhero document list
paperhero document list --folder-id <id>

# Show document metadata and revisions
paperhero document show <id>

# Download and decrypt a document
paperhero document download <id> ./output.pdf --password <pass>
paperhero document download <id> ./output.pdf --revision 1 --password <pass>

# Search documents
paperhero document search "invoice december"
paperhero document search "contract" --fulltext

# Delete a document
paperhero document delete <id>

paperhero folder

Manage the folder structure.

# List all folders
paperhero folder list

# Show folder tree
paperhero folder tree

# Show folder details and contents
paperhero folder show <id>

# Create a folder
paperhero folder create "Invoices"
paperhero folder create "Invoices" --parent-id <id>
paperhero folder create "Invoices/2024/December" --parent-id <id>

# Delete a folder
paperhero folder delete <id>
paperhero folder delete <id> --recursive

paperhero email-ingress

Manage email ingress (receive documents via email).

# Show email ingress status
paperhero email-ingress status

# Enable/disable email ingress
paperhero email-ingress enable
paperhero email-ingress disable

# Get the ingress email address (bare output, for scripting)
paperhero email-ingress address

# Manage sender whitelist
paperhero email-ingress whitelist list
paperhero email-ingress whitelist add [email protected]
paperhero email-ingress whitelist remove [email protected]
paperhero email-ingress whitelist enable
paperhero email-ingress whitelist disable

paperhero job

Monitor background jobs.

# List recent jobs
paperhero job list
paperhero job list --page 2

# Show job details and logs
paperhero job show <id>

paperhero version

Print the current CLI version, OS, and architecture.

paperhero version
paperhero version --json

paperhero update

Update the CLI to the latest version. Downloads the correct binary for your platform, verifies the checksum, and replaces itself in-place.

# Check for updates without installing
paperhero update --check

# Update to the latest version
paperhero update

AI Agent Integration

The CLI is designed from the ground up for use by AI agents and automation systems. Key design principles:

1. Fully non-interactive -- no prompts, no stdin reads, no confirmations
2. JSON output -- use --json flag for structured, parseable output
3. Environment variables -- all secrets via env vars (no command-line history exposure)
4. Deterministic exit codes -- 0 for success, 1 for errors
5. Descriptive errors -- error messages include the fix (e.g. "provide --password or set PAPERHERO_PASSWORD")

Connect your AI agent to PaperHero

Running OpenClaw, NemoClaw, Claude Code, Cline, or OpenCode? paperhero is the missing link between your AI agent and your document archive. Any agent that can run a shell command gets full access to your inbox, documents, and folders -- without writing a single line of integration code.

Example: Automated inbox processing

export PAPERHERO_PASSWORD=secret
paperhero login --customer-id myco --email [email protected] --password "$PAPERHERO_PASSWORD"

# List ready inbox items
items=$(paperhero inbox list --ready-only --json)

# Process each item using AI recommendations
echo "$items" | jq -r '.[] | select(.ready==true) | .id' | while read id; do
  paperhero inbox import "$id" --use-ai-defaults --password "$PAPERHERO_PASSWORD"
done

Example: Document search and download

# Search for documents
results=$(paperhero document search "invoice december" --json)

# Download the first result
doc_id=$(echo "$results" | jq -r '.[0].id')
paperhero document download "$doc_id" ./invoice.pdf --password "$PAPERHERO_PASSWORD"

Example: Email ingress setup

# Enable email ingress and get the address
paperhero email-ingress enable
address=$(paperhero email-ingress address)
echo "Send documents to: $address"

# Set up sender whitelist
paperhero email-ingress whitelist enable
paperhero email-ingress whitelist add [email protected]
paperhero email-ingress whitelist add [email protected]

Encryption

All documents stored in PaperHero are encrypted. When downloading documents via the CLI, decryption happens locally on your machine:

1. Login caches the user's encrypted private key and embeddings password in the session file
2. Download/Import commands decrypt the private key using your password, then use it to decrypt document files locally
3. The password is never stored -- it must be provided via --password or PAPERHERO_PASSWORD each time

For E2E encrypted accounts, the private key is not stored on the server. You must provide the key file exported during E2E setup via --key-file and --key-password.

Advanced

The --api-url flag and PAPERHERO_API_URL environment variable can override the API endpoint if needed.

License

MIT