CLI reference

calco is a single binary with several subcommands. Build it once and use it from the command line, a Docker container, or a CI script.

The calco CLI ships with the self-hosted enterprise distribution. If you are on the Cloud subscription you do not run the binary yourself, but these commands document the same engine that powers the hosted API. See Self-hosting & deployment for how the binary is delivered and run.

bash

go build -o bin/calco ./cmd/calco
./bin/calco <command> [flags]

All flags use the -flag value or -flag=value form (Go standard library flag package). Run any command with -h to print its built-in help.

`calco convert`

Render a template file to one of the supported output formats. Accepts .xlsx and .docx input; the source type is auto-detected.

bash

calco convert -in <file> [flags]

Input / output

Flag	Default	Description
`-in <path>`	(required)	Source `.xlsx` or `.docx` template file.
`-out <path>`	inferred	Output file or directory. When omitted, the filename is derived from `-in` and `-format`. For image formats (see below) this can be a directory path or a `.zip` file.
`-format <fmt>`	inferred	Output format. One of `pdf`, `html`, `docx`, `xlsx`, `jpg`, `webp`, or `original`. When `-out` is given without `-format`, the format is inferred from the output file extension. When both are omitted, DOCX source defaults to `docx` and XLSX source defaults to `html`.
`-sheet <name>`	(all sheets)	XLSX only. Export a specific sheet by name.
`-title <text>`	`Excel Export`	XLSX only. Sets the HTML `<title>` element used during intermediate rendering; also affects the output filename when `-out` is omitted.

Data injection

Flag	Default	Description
`-data <path>`	—	Path to a JSON file whose contents supply `{d.*}` placeholder values. The top-level object is used directly; no wrapping needed.
`-data-json <json>`	—	Inline JSON string for `{d.*}` values. Use instead of `-data` when the payload is small or generated on the fly. Mutually exclusive with `-data` in practice (both can be given; `-data` is read first).
`-data-complement <path>`	—	Path to a JSON file for `{c.*}` complement placeholder values. Loaded into the `c` submap alongside the main data.
`-data-complement-json <json>`	—	Inline JSON for `{c.*}` values.
`-lang <code>`	—	Language code (e.g. `en`, `es`) used to select the active sub-map from the translations file.
`-translations <path>`	—	Path to a JSON file mapping language codes to translation maps, e.g. `{"en":{"greeting":"Hello"},"es":{"greeting":"Hola"}}`. The sub-map for `-lang` is placed under `{t.*}` placeholders.
`-translations-json <json>`	—	Inline JSON translations map (same shape as `-translations`).

Image options (`jpg` / `webp` only)

Flag	Default	Description
`-dpi <n>`	`150`	Dots-per-inch for rasterization. Clamped to `72`–`300`.
`-quality <n>`	`0`	Compression quality, `1`–`100`. `0` means use the format's built-in default: 85 for JPEG, 80 for WebP. WebP quality controls compression effort; output is always lossless VP8L.

Multi-page image output. When the source has more than one page, -out determines how pages are written:

.zip extension → a ZIP archive with entries page-001.jpg (zero-padded).
Directory path (existing or no extension) → one file per page inside the directory.
No -out → a directory named out_jpg or out_webp is created automatically.
Single file extension (e.g. -out result.jpg) on a multi-page source → error; use a directory or .zip instead.

PDF signing (`-format=pdf` only)

Pass -sign to digitally sign the rendered PDF in the same step. The certificate must be a PKCS#12 (.p12 / .pfx) file.

Flag	Default	Description
`-sign`	`false`	Enable PDF signing. Requires `-format=pdf` and `-cert`.
`-cert <path>`	(required with `-sign`)	Path to the PKCS#12 certificate file.
`-password <pass>`	—	Password for the PKCS#12 file. Falls back to the `UNIKIA_SIGN_PASSWORD` environment variable when omitted.
`-sign-reason <text>`	—	Free-text reason embedded in the signature (e.g. `Approved`).
`-sign-location <text>`	—	Location text embedded in the signature (e.g. `Madrid`).
`-sign-contact <text>`	—	Contact information embedded in the signature.
`-sign-name <text>`	certificate CN	Signer display name. Defaults to the Common Name from the certificate.
`-sign-tsa <url>`	—	RFC 3161 timestamp authority URL. When set, an authenticated timestamp is embedded in the signature.
`-sign-tsa-user <user>`	—	HTTP Basic Auth username for the TSA endpoint.
`-sign-tsa-pass <pass>`	—	HTTP Basic Auth password for the TSA endpoint.
`-sign-visible`	`false`	Draw a visible signature widget on the page.
`-sign-page <n>`	`0`	Page number for the visible widget. `0` means the last page.
`-sign-rect <x,y,w,h>`	`150,15,55,18`	Position and size of the visible signature widget in millimetres (`x,y,width,height`).
`-sign-image <path>`	—	Image file to embed inside the visible signature widget.

Examples

bash

# Render an XLSX template to PDF with data
calco convert -in invoice.xlsx -data payload.json -format pdf -out invoice.pdf

# Render and sign in one step
calco convert -in invoice.xlsx -data payload.json \
  -format pdf -sign -cert company.p12 -password 's3cr3t' -out signed.pdf

# Export a specific sheet as HTML
calco convert -in report.xlsx -sheet "Summary" -format html -out summary.html

# Render DOCX to JPEG pages, one per file in a directory
calco convert -in letter.docx -data data.json -format jpg -dpi 200 -out ./pages/

# Render DOCX to a ZIP of WebP pages
calco convert -in letter.docx -data data.json -format webp -out pages.zip

# Render with inline data and translation
calco convert -in template.xlsx \
  -data-json '{"name":"Ada"}' \
  -translations-json '{"en":{"hello":"Hi"}}' -lang en \
  -format pdf -out out.pdf

# Return the filled-in XLSX (data substituted, no conversion)
calco convert -in template.xlsx -data payload.json -format original -out filled.xlsx

`calco serve`

Start the HTTP API server (Gin). The server exposes all web UI and API routes on the specified address.

bash

calco serve [flags]

Flag	Default	Description
`-addr <addr>`	`:8080`	TCP address to listen on, in the form `host:port` or just `:port`.

The server is configured primarily through environment variables (database driver, storage driver, OIDC, etc.). See CLAUDE.md or the project README for the full list of environment variables.

Example

bash

# Listen on all interfaces, port 9000
calco serve -addr :9000

# Listen only on localhost
calco serve -addr 127.0.0.1:8080

`calco sign`

Sign an existing PDF file with a PKCS#12 certificate. Use this when you already have a rendered PDF and want to sign it as a separate step. For signing during rendering in one pass, use calco convert -sign instead.

bash

calco sign -in <file> -out <file> -cert <file> [flags]

Required flags

Flag	Description
`-in <path>`	Input PDF file to sign.
`-out <path>`	Output path for the signed PDF. The file must not already exist.
`-cert <path>`	Path to the PKCS#12 (`.p12` / `.pfx`) certificate file.

Certificate & identity

Flag	Default	Description
`-password <pass>`	—	PKCS#12 password. Falls back to the `UNIKIA_SIGN_PASSWORD` environment variable.
`-name <text>`	certificate CN	Signer display name embedded in the signature.
`-reason <text>`	—	Reason text (e.g. `Approved by legal`).
`-location <text>`	—	Location text (e.g. `Madrid, Spain`).
`-contact <text>`	—	Contact information text.

Timestamp authority (TSA)

Flag	Default	Description
`-tsa <url>`	—	RFC 3161 timestamp authority URL. Embeds an authenticated timestamp in the signature.
`-tsa-user <user>`	—	HTTP Basic Auth username for the TSA.
`-tsa-pass <pass>`	—	HTTP Basic Auth password for the TSA.

Flag	Default	Description
`-visible`	`false`	Draw a visible signature field on the page.
`-page <n>`	`0`	Page to place the widget on. `0` means the last page.
`-rect <x,y,w,h>`	`150,15,55,18`	Widget position and size in millimetres (`x,y,width,height`). Origin is the bottom-left corner of the page.
`-image <path>`	—	Image to embed inside the visible widget (e.g. a scanned signature).

Examples

bash

# Minimal invisible signature
calco sign -in document.pdf -out signed.pdf -cert company.p12 -password s3cr3t

# With metadata and a timestamp authority
calco sign -in document.pdf -out signed.pdf -cert company.p12 \
  -reason "Approved" -location "Madrid" -tsa https://tsa.example.com/ts

# Visible widget on the last page, custom position
calco sign -in document.pdf -out signed.pdf -cert company.p12 \
  -visible -page 0 -rect "20,20,60,20" -image signature.png

`calco verify`

Verify the digital signatures in a PDF and print a JSON report to stdout. Exits with a non-zero code if any signature is invalid.

bash

calco verify -in <file>

Flag	Default	Description
`-in <path>`	(required)	PDF file to inspect.

The report is a JSON object with a signatures array. Each entry carries the signer name, validity flag, certificate chain, and signing time. Exit code 1 is returned when at least one signature reports "valid": false.

Example

bash

# Verify and pretty-print the report
calco verify -in signed.pdf

# Check the exit code in a script
calco verify -in signed.pdf && echo "All signatures valid" || echo "INVALID"

`calco storage migrate`

Import templates from an older file-based layout (a directory of <id>/meta.json files) into the current database catalogue. Supports both local-keep and S3 storage destinations.

bash

calco storage migrate -from <dir> -team-id <id> [flags]

The command is safe by default: it runs as a dry run unless you explicitly pass -dry-run=false.

Required flags

Flag	Description
`-from <path>`	Source directory. Each subdirectory must contain a `meta.json` describing the template and its versions.
`-team-id <id>`	Organization / team ID to assign to every migrated template.

Optional flags

Flag	Default	Description
`-to-driver <driver>`	`local-keep`	Where to write blob files. `local-keep` leaves blobs in place and records their existing path; `s3` uploads each file to the bucket configured via `STORAGE_DRIVER` / `S3_*` environment variables.
`-db <path>`	`CALCO_DB_PATH` env → `/app/data/app.db`	SQLite database path. Ignored when `CALCO_DB_DRIVER=postgres` (use `DATABASE_URL` instead).
`-dry-run`	`true`	Print a plan of what would be migrated without writing anything. Pass `-dry-run=false` to apply.

Database selection

The migration command respects the same environment variables as the server:

Env var	Effect
`CALCO_DB_DRIVER`	`sqlite` (default) or `postgres`.
`CALCO_DB_PATH`	SQLite database path (overridden by `-db` flag).
`DATABASE_URL`	Postgres DSN, required when `CALCO_DB_DRIVER=postgres`.

Examples

bash

# Preview what would be migrated (dry run, default)
calco storage migrate -from /old/templates -team-id org_abc123

# Apply the migration to SQLite
calco storage migrate -from /old/templates -team-id org_abc123 -dry-run=false

# Apply the migration and upload blobs to S3
STORAGE_DRIVER=s3 \
AWS_REGION=eu-west-1 \
AWS_S3_BUCKET=my-templates \
  calco storage migrate \
    -from /old/templates \
    -team-id org_abc123 \
    -to-driver s3 \
    -dry-run=false

# Migrate to a Postgres-backed instance
CALCO_DB_DRIVER=postgres \
DATABASE_URL=postgres://user:pass@localhost:5432/calco?sslmode=disable \
  calco storage migrate -from /old/templates -team-id org_abc123 -dry-run=false

`calco version`

Print the build version string and exit.

bash

calco version

No flags. Outputs a single line, e.g. calco 1.4.2 (or calco dev for local builds).

Exit codes

Code	Meaning
`0`	Success.
`1`	Runtime error (I/O failure, signing error, invalid signature, etc.).
`2`	Usage error — missing required flag or unknown command.
`3`	Certificate load error (`calco sign` / `calco convert -sign`).
`4`	Signing operation failure (`calco sign`).

Environment variables

The CLI honours the same environment variables as the server for database access and storage configuration. The variables most relevant to CLI usage are:

Variable	Used by	Description
`UNIKIA_SIGN_PASSWORD`	`convert`, `sign`	PKCS#12 certificate password. Avoids passing the password on the command line.
`CALCO_DB_DRIVER`	`storage migrate`	`sqlite` or `postgres`.
`CALCO_DB_PATH`	`storage migrate`	SQLite database file path.
`DATABASE_URL`	`storage migrate`	Postgres DSN (required when `CALCO_DB_DRIVER=postgres`).
`STORAGE_DRIVER`	`storage migrate`	`s3` — required when `-to-driver=s3`.
`TEMPLATE_LOCALE`	`convert`	Default locale for number and currency formatters (e.g. `es-ES`).

CLI reference

calco convert

Input / output

Data injection

Image options (jpg / webp only)

PDF signing (-format=pdf only)

Examples

calco serve

Example

calco sign

Required flags

Certificate & identity

Timestamp authority (TSA)

Visible signature widget

Examples

calco verify

Example

calco storage migrate

Required flags

Optional flags

Database selection

Examples

calco version

Exit codes

Environment variables

`calco convert`

Image options (`jpg` / `webp` only)

PDF signing (`-format=pdf` only)

`calco serve`

`calco sign`

`calco verify`

`calco storage migrate`

`calco version`