Shablonix CLI

Command-line client for the existing Shablonix generation API. Requires Node 20.12+.

Install

npm install -g @shablonix/cli
shablonix interactive

Or run it without installing: npx @shablonix/cli --help. Full guide: https://shablonix.online/docs/cli

Run from this workspace

pnpm install
pnpm --filter @shablonix/cli cli interactive

pnpm --filter @shablonix/cli cli --help only displays available commands. The installed binary also accepts shablonix --interactive.

Guided interactive mode

The guided mode opens a colored menu with multi-step flows for connecting an API key, generating one document, submitting a batch, checking jobs, and downloading files. It masks the key while typing, reviews the template and input before submission, and lets you wait for completion or return to the menu. Use it in a terminal; scripts and agents should use the flag-based commands below. Colors are suppressed when NO_COLOR is set.

Authenticate

Create an API key in the Shablonix dashboard with documents:generate scope. The full key is shown once. Import it without putting it in a command argument:

shablonix auth login --key-stdin < /secure/path/shablonix-api-key
shablonix auth status

auth login verifies the key through the public GET /v1/generate route before saving it to ~/.config/shablonix/auth.json with mode 0600. auth logout removes the local copy; revoke the key in the dashboard when you want to disable it server-side. For CI or an agent, set SHABLONIX_API_KEY through your secret manager instead of saving a local key. SHABLONIX_BASE_URL selects a self-hosted API with an environment key. auth login --base-url selects one for a saved key. HTTPS is required except for local loopback development.

Generate one document

shablonix generate --template cm123 --data-file invoice.json
shablonix generation status <generation-id>
shablonix generation download <generation-id> --output invoice.pdf

For a plain text file used as a template's text data field:

shablonix generate --template cm123 --text-file letter.txt --wait --output letter.pdf

To receive the file in the generate response itself, with no job to poll and no copy kept on Shablonix:

shablonix generate --template cm123 --data-file invoice.json --stream --output invoice.pdf

--stream requires --output and is billed when rendering finishes. Add --idempotency-key <key> (8-200 visible ASCII characters, such as an invoice number) to any generate so that rerunning the command returns the same document without another charge. A keyed stream is retained for the normal window so that it can be replayed.

--docx-template <id> selects an existing uploaded DOCX template; it does not upload a new DOCX file. Use --format docx for DOCX output. --output waits for completion and streams the result to a new private local file. The default submission returns the job ID immediately. Use --json for ordinary JSON output; the default is compact TOON output for agents. All commands support --help.

Submit a PDF batch

One server batch uses one published template and 1–100 data objects. CSV, JSON arrays, and JSONL files are supported:

customer.name,invoice.number,amount
Ada,INV-001,12.50
Bob,INV-002,24.00

shablonix batch submit --template cm123 --file invoices.csv
shablonix batch status <batch-id>

Dotted CSV headers produce nested JSON data. CSV values remain strings, preserving invoice numbers and decimal text. JSON and JSONL files contain one data object per item. The CLI rejects batches outside 1–100 rows instead of silently splitting them, since the server has no batch idempotency key and a partly submitted multi-request file would be difficult to retry safely. For multiple templates, submit a separate batch per template. For standard API download URLs, completed batch results include a generationId; download an item with shablonix generation download <generationId> --output <file>.

Webhooks

Configure an account webhook in the dashboard and select document.completed, document.failed, batch.completed, and batch.failed as needed. These account events are HMAC signed and fire for CLI submissions as they do for SDK/API submissions. The public client API does not expose account webhook settings or usage, so manage and inspect them in the dashboard. The CLI does not set a per-request callback because those callbacks are unsigned. Polling through generation status or batch status is available when there is no receiver.

The CLI does not handle a user's password or MFA challenge. Authentication currently imports a dashboard-created, scoped API key. A browser/device authorization flow would require a dedicated server contract before the CLI could obtain a key without the user copying it.