usefin

The universal CLI for finance software. One command grammar, every provider.

usefin [provider]:[object]:[verb] --[flags]

$ usefin stripe:invoices:list --status open --json
$ usefin quickbooks:bills:list --status overdue --csv
$ usefin xero:contacts:list --type customer --limit 10

No sign-up. No account. MIT licensed. Install and go.

• Full command reference: docs/COMMAND_REFERENCE.md
• Supported providers (GA, real API status): docs/SUPPORTED_PROVIDERS.md
• Roadmap & backlog: docs/ROADMAP.md · docs/OBJECT_AND_VERB_COVERAGE.md · docs/PROVIDER_BACKLOG.md
• Multi-tenant / SaaS integration: docs/MULTI_TENANT.md
• Contributing (new provider plugin): CONTRIBUTING.md

Getting started

1. Install — npm install -g @usefin/cli or clone and pnpm install && pnpm run build.
2. Verify — pnpm run usefin doctor (or usefin doctor) to see registered providers.
3. Authenticate — usefin auth:login <provider> --api-key YOUR_KEY for API-key providers, or usefin auth:login <provider> --interactive for OAuth2 (e.g. Xero; set env vars per COMMAND_REFERENCE).
4. First commands — usefin <provider>:<object>:list, usefin <provider>:<object>:get <id>, then create/update with --data '{"key":"value"}' where supported. See docs/COMMAND_REFERENCE.md and docs/SUPPORTED_PROVIDERS.md.
5. Update — npm update -g @usefin/cli (or see Install / Update / Uninstall below).

Demo

To re-record: asciinema rec docs/demo.cast then export to GIF, or use a screen recorder and save as docs/demo.gif.

Install / Update / Uninstall

Install

npm install -g @usefin/cli

Or build from source:

git clone https://github.com/usefin/usefin.git && cd usefin
pnpm install
pnpm run build
node packages/core/bin/run.js --version

Requires Node.js >= 18 and pnpm.

Update

npm update -g @usefin/cli

Or to force the latest version: npm install -g @usefin/cli@latest. With pnpm: pnpm update -g @usefin/cli.

Uninstall

npm uninstall -g @usefin/cli

With pnpm: pnpm remove -g @usefin/cli. Uninstall removes the CLI only; credentials and config in ~/.config/usefin/ are left behind. Delete that directory for a full removal.

Usage

# authenticate
usefin auth:login stripe --api-key sk_live_...
usefin auth:login xero --interactive

# query (list, get, create, update, delete where supported)
usefin stripe:customers:list --status active --json
usefin xero:invoices:list --status overdue --csv
usefin quickbooks:payments:get pay_abc123 --json
usefin stripe:customers:create --data '{"email":"[email protected]"}'
usefin xero:contacts:update con_abc123 --data '{"Name":"Acme Inc"}'
usefin stripe:customers:delete cus_abc123

# pipe and script
usefin stripe:invoices:list --status open --json | jq '.[].amount_due'
usefin ramp:expenses:list --csv > expenses.csv

# interactive mode
usefin stripe:customers:list --interactive

# diagnostics
usefin auth:status
usefin doctor

Standard Flags

Every command accepts:

| Flag | Description | |------|-------------| | --json | Raw JSON output | | --csv | CSV output | | --filter "key=value" | Filter results | | --limit N | Cap result count | | --interactive | Launch interactive TUI | | --dry-run | Preview only | | --audit | Log to audit trail | | --jsonl | JSONL output (one object per line) | | --data '{}' | JSON body for create/update (required for those verbs) | | --verbose / -v | Debug output (stderr) |

Providers

121 supported (GA) providers across 16 categories with real API when authenticated and mock fallback when not. Same grammar, same flags, same output format.

See docs/SUPPORTED_PROVIDERS.md for the full list. Roadmap and provider backlog (600+ catalog): docs/ROADMAP.md, docs/PROVIDER_BACKLOG.md.

CLI plugins: Schema-driven; only supported providers are exposed. @usefin/plugin-stripe, @usefin/plugin-accounting (23 providers), and 20 other category plugins. Every provider with a real API client has comprehensive object coverage.

Architecture

Schema-driven monorepo managed by pnpm workspaces. CLI framework is oclif v4 with plugins.

Providers declare a schema (objects, verbs, flags) and the CommandFactory generates all commands at load time. Zero copy-paste — adding a provider is writing one schema file.

packages/
  core/                 @usefin/core — CLI framework, auth, output, command factory
    src/
      commands/         auth/login, auth/status, auth/logout, auth/rotate, doctor
      lib/
        auth/           AES-256-GCM encrypted credential storage + keytar adapter
        commands/       CommandFactory — schema-to-command generator
        errors/         Standardized FinError with 9 error codes
        http/           HTTP client with retry, rate limiting, pagination
        interactive/    @clack/prompts interactive list/select
        output/         JSON / CSV / Table / JSONL renderer
        providers/      Provider registry + schema types
    bin/run.js          Entry point

  plugin-stripe/        @usefin/plugin-stripe — schema-driven
    src/
      schema.ts         Stripe provider schema (15 objects)
      lib/
        stripe-client.ts  Real Stripe API client with pagination
        mock-data.ts      Mock data fallback

  plugin-accounting/    @usefin/plugin-accounting — schema-driven
    src/
      schemas/          14 provider schemas + shared base objects
      lib/
        mock-data.ts    Mock data for all providers

site/                   Documentation site (Express, port 5000)

Multi-tenant / SaaS

usefin supports multi-tenant SaaS integration in two modes:

• CLI mode (config dir per tenant): Set USEFIN_CONFIG_DIR to isolate credentials and audit logs per tenant. Each tenant gets its own config directory with separate encrypted credential storage and audit trail.

  USEFIN_CONFIG_DIR=/data/tenants/tenant_123 usefin xero:invoices:list --json

• Library mode (injectable auth): Use runWithAuth(authManager, fn) to scope authentication per request using AsyncLocalStorage. Implement a custom CredentialStore backed by your database or secrets manager.

See docs/MULTI_TENANT.md for the full integration guide, credential contract, security responsibilities, and code examples.

Tech Stack

| Component | Library | |-----------|---------| | CLI framework | oclif v4 (explicit strategy) | | Language | TypeScript (ES2022, Node16 modules, strict) | | Monorepo | pnpm workspaces | | Interactive UI | @clack/prompts | | Output | chalk, cli-table3 | | Validation | Zod | | Auth | AES-256-GCM encrypted storage, keytar adapter | | HTTP | Native fetch with retry + rate limiting | | Testing | Vitest |

Security

• Credentials encrypted at rest (AES-256-GCM) with OS keychain fallback via keytar
• No telemetry, no data persistence, no proxy
• Standardized error codes — no secret leakage in error output
• Token exchange errors are sanitized — no raw response bodies or secrets in error output
• Verbose mode (--verbose) redacts auth endpoint responses for security
• Multi-tenant security responsibilities documented in docs/MULTI_TENANT.md
• --dry-run previews without executing
• See SECURITY.md for vulnerability reporting

Contributing

See CONTRIBUTING.md.

License

MIT