SingleFax CLI

Official CLI for SingleFax: send a fax with an API key and prepaid credits, or start Checkout for other SKUs.

Chat apps should use MCP (https://singlefax.com/mcp). Autonomous Stripe MPP payments use Stripe Link CLI, not this tool.

Install

npm i -g @singlefax/cli
# or
npx @singlefax/cli --help

Create a scoped key at https://singlefax.com/dashboard/api-keys (fax:send, fax:read, credits:read, credits:checkout). Prepay credits in the dashboard, or run singlefax credits buy / singlefax buy credit_pack.

export SINGLEFAX_API_KEY=sf_live_…
# or
singlefax config set api-key sf_live_…

Send

Pass the original file. PDF, Word, Excel, PowerPoint, RTF, plain text, and images (JPEG, PNG, TIFF, GIF, WebP, BMP, HEIC) are accepted. Do not convert to PDF first — send the original; we convert before sending.

npx @singlefax/cli send ./document.docx --to +14155552671
npx @singlefax/cli send ./document.pdf --to +14155552671 --wait --json

--help, send --help, and skus work without a key.

Commands

| Command | API | | --- | --- | | send FILE --to +E164 [--cover] [--wait] | POST /uploads → PUT → POST /faxes | | quote [--to +E164] [--pages 10] [FILE] | POST /api/v1/faxes/quote | | status <id> | GET /api/v1/faxes/:id | | list [--limit 20] [--offset 0] | Outbound faxes you sent (fax:read). GET /api/v1/faxes | | numbers | GET /api/v1/numbers | | numbers buy [--sku inbound_30day] [--country US] [--state CA] | POST /api/v1/numbers | | skus | GET /api/v1/skus | | buy <sku> [--dollars 20] [--country US] [--state CA] | POST /api/v1/checkout | | credits | GET /api/v1/credits | | credits buy [--dollars 20] | POST /api/v1/credits/checkout | | config set api-key sf_live_… | writes ~/.config/singlefax/config.json |

buy SKUs: credit_pack, inbound_30day, monthly-basic, annual-basic, monthly-business, annual-business, lifetime-basic, lifetime-pro. HIPAA / EIN / IRS print a website URL. Send a document with send, not buy. Get a number with numbers buy (default 30-day). Do not convert to PDF first.

Flags: --json, --api-key, --api-url (default https://api.singlefax.com).

Do not send PHI through this CLI. Covered Entities use the website HIPAA Secure path with an electronic BAA.

Publish (maintainers)

Releases use npm trusted publishing (OIDC). There is no NPM_TOKEN.

On npmjs.com → @singlefax/cli → Settings → Trusted Publisher → GitHub Actions:

| Field | Value | | --- | --- | | Organization or user | SingleFax | | Repository | singlefax-app | | Workflow filename | ci-cd-cli.yml | | Environment name | leave empty | | Allowed actions | npm publish |

Configure this on the package before the first Actions publish (npm does not validate the form until publish). Provenance is generated automatically. The repository.url in package.json must stay https://github.com/SingleFax/singlefax-app.git.

A push to main that touches this package (or this workflow) bumps the patch version from whatever is already on npm, commits chore(cli): x.y.z [skip ci], and publishes. Same bump happens if you run Actions → CLI → Publish from main. Do not bump package.json by hand for patches.

Major / minor: set "version" in package.json above the published line, or tag cli-v2.0.0. Autopublish never increments major/minor on its own.