@sinoia/hubdoc-tools

HubDoc Tools CLI

Command-line tool for HubDoc document import/export with multi-source support and OAuth2 authentication.

Two binaries are installed: hubdoc-tool (full name) and hubdoc (short alias). Use hubdoc for one-shot CRUD operations and headless / agent usage; hubdoc-tool keeps the legacy bulk import/export workflows.

LLM / Headless usage

Single-operation CRUD commands (hubdoc workspaces|folders|files ...) are designed to be driven by LLMs and CI scripts: every subcommand accepts --json (structured stdout, structured stderr errors, non-zero exit on failure) and refuses to prompt when --yes is omitted in --json mode.

See docs/llm-usage.md for the contract, a full command reference, and a worked agent session example.

hubdoc whoami --json
hubdoc workspaces ls --json | jq '.[].label'
hubdoc files upload ./report.pdf --folder=$FOLDER_ID --json

Installation

Global (NPM)

npm install -g @sinoia/hubdoc-tools
hubdoc --version

Development

# From monorepo root
npm install
npm run build:cli
npm run dev:cli -- --help

Configuration

OAuth2 (Automatic)

export HUBDOC_API_URL=https://your-instance.hubdoc.sinoia.cloud
export HUBDOC_OAUTH_CLIENT_ID=your-client-id
export HUBDOC_OAUTH_CLIENT_SECRET=your-client-secret
export HUBDOC_OAUTH_SCOPES="read write"

Or create .env file with the same variables.

Authentication is automatic:

• First run opens browser for authorization
• Token saved to .hubdoc-config.json
• Auto-refresh before expiration
• No manual token management required

See OAUTH_SETUP.md for details.

Commands

Import

Direct Import

# Preserves folder structure
hubdoc-tool import --direct ./documents

CSV Mapping Import

# Generate mapping
hubdoc-tool generate-mapping ./documents

# Edit mapping.csv, then import
hubdoc-tool import --mapping mapping.csv

Plugin Import

# From external source (OneDrive, S3, etc.)
hubdoc-tool --engine onedrive import --source "/Shared Documents"
hubdoc-tool --engine googledrive import --source "My Drive/Docs"
hubdoc-tool --engine s3 import --source "s3://bucket/path"

Options:

• --concurrent N - Parallel jobs (default: 3)
• --skip-existing - Skip already imported documents
• --dry-run - Validate without importing
• --validate-all - Strict validation

Export

# Scan HubDoc and generate mapping
hubdoc-tool export --scan

# Export using mapping
hubdoc-tool export --mapping export-mapping.csv

# Export with XML metadata
hubdoc-tool export --generate-xml-metadata

# Filters
hubdoc-tool export --scan --project "Project Name"
hubdoc-tool export --scan --domain "Domain Name"

See EXPORT-DOCUMENTATION.md for details.

Interactive Mode

hubdoc-tool --interactive
hubdoc-tool -i

CSV Mapping Format

Import Mapping

File Path;Target Folder;Workspace;Metadata (key: value, parent.child: value);Permissions (users:r:email users:w:email | groups:Name);Auto Classify;Status;Error;Document ID;Bulk Upload ID

Example:

/docs/invoice.pdf;Finance/Invoices;Accounting;invoice_number: INV-001, amount: 1500;users:john@ex.com | groups:Finance;true;pending;;;

Export Mapping

Document ID,Document Name,Projects (project:folder|project:folder),Download URL,Target Path (editable),Metadata (JSON)

Metadata Format

Simplified key-value format:

key: value, parent.child: value

Examples:

invoice_number: INV-001, amount: 1500
supplier.name: Acme, supplier.vat: FR123, amount: 2500

Types auto-detected: numbers, booleans, null.

Permissions Format

Natural format:

users:email1,email2 | users:w:admin@ex.com | groups:Group Name | groups:w:Admins

• No suffix = READ
• :r = READ explicit
• :w = WRITE
• Supports spaces in group names

Examples:

users:viewer@ex.com | users:w:editor@ex.com | groups:Finance
groups:All Staff | groups:w:Management

Plugins

Available plugins:

• core - Core DMS integration
• o365-mail - Office 365 Mail via Graph API
• filesystem - Local filesystem
• onedrive - Microsoft OneDrive
• googledrive - Google Drive
• dropbox - Dropbox
• aws-s3 - Amazon S3
• azure-blob - Azure Blob Storage
• sharepoint - SharePoint
• alfresco - Alfresco ECM
• nuxeo - Nuxeo DMS
• opentext - OpenText
• box - Box.com

See PLUGINS.md for plugin development.

Features

Import

• Direct import with folder structure preservation
• CSV mapping for precise control
• Multi-source support via plugins
• Permissions (read/write by user/group)
• Simplified metadata format
• Concurrent processing
• Dry-run validation
• Skip existing documents
• OAuth2 automatic authentication

Export

• Scan HubDoc to generate mapping
• Custom folder structure
• XML metadata generation
• Filters by project/domain
• Concurrent downloads

Examples

Import from Local Filesystem

hubdoc-tool import --direct ./invoices --concurrent 5

Import from OneDrive

export ONEDRIVE_CLIENT_ID=your-id
export ONEDRIVE_CLIENT_SECRET=your-secret
export ONEDRIVE_TENANT_ID=your-tenant

hubdoc-tool --engine onedrive import --source "/Shared Documents"

Export with Filters

hubdoc-tool export --scan --project "My Project" --domain "Finance"
hubdoc-tool export --mapping export.csv --output ./exports

Testing

# From monorepo root
npm run test:cli

# Specific tests
npm test -- permissions
npm test -- metadata

# Coverage
npm run test:coverage

Version

1.4.0

License

MIT