CLI

This is the help of rusticdoc 0.1.0. The CLI is the same binary as the service. See Install for how to run it.

rusticdoc

Templates in, documents out. Run `serve` for the HTTP API.

Usage: rusticdoc [OPTIONS] <COMMAND>

Commands:
  render          Fill a template and run the steps, writing one file
  convert         Convert one or more documents
  serve           Run the HTTP service. Settings come from RUSTICDOC_* variables
  openapi         Print the OpenAPI description as JSON
  health          Check a running service, for container health checks. Exits 0 when up
  engines         Show the engines this machine has
  pdf             PDF operations: merge, split, rotate, flatten, optimize, encrypt, metadata, bookmarks, embed, watermark, stamp, sign, factur-x, forms
  validate        Check a template against sample data and list every problem
  translate       Create or update `<lang>.json` with the keys templates pass to `t`. Translations already there are kept, new keys get an empty text, and keys no template uses any more are listed, not removed
  webhook-secret  Print the key a caller's webhook deliveries are signed with, in hex, from RUSTICDOC_WEBHOOK_SECRET. A receiver decodes it and verifies with it
  help            Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Log verbosity: -v for debug, -vv for trace
  -h, --help        Print help
  -V, --version     Print version

rusticdoc render

Fill a template and run the steps, writing one file

Usage: rusticdoc render [OPTIONS] <TEMPLATE>

Arguments:
  <TEMPLATE>  The template file

Options:
  -d, --data <DATA>
          JSON file with the data the template sees
  -v, --verbose...
          Log verbosity: -v for debug, -vv for trace
      --ctx <CTX>
          JSON file visible as `ctx`
      --lang <LANG>
          The language, such as `fr` or `fr-CA`: picks translations and, when CLDR has data for it, how numbers, money and dates are written
      --translations <TRANSLATIONS>
          JSON file of translations by language, as the service's `translations` field: `{"fr": {"total": "Montant"}}`
      --timezone <TIMEZONE>
          The time zone `date` shows moments in: `+02:00` or `Europe/Paris`
  -s, --steps <STEPS>
          Steps in order: convert, pdfa, metadata, encrypt, merge, sign. `sign` comes last and uses RUSTICDOC_SIGNING_KEY and RUSTICDOC_SIGNING_CERT [default: ""]
      --to <TO>
          Output format for `convert` [default: pdf]
      --pdfa <PDFA>
          PDF/A level for `pdfa` [default: PDF/A-2b]
      --metadata <METADATA>
          JSON object for `metadata`
      --user-password <USER_PASSWORD>

      --owner-password <OWNER_PASSWORD>

      --merge-with <MERGE_WITH>
          Extra PDFs for `merge`
      --asset <ASSETS>
          An image, stylesheet or font an HTML page names by file name. Repeat it for each
      --html-engine <HTML_ENGINE>
          What turns HTML into PDF: fulgur or libreoffice [default: fulgur]
  -o, --output <OUTPUT>
          Where to write the result. Defaults to the template's name with the output extension
  -h, --help
          Print help

rusticdoc convert

Convert one or more documents

Usage: rusticdoc convert [OPTIONS] [FILES]...

Arguments:
  [FILES]...  Documents to convert

Options:
      --to <TO>                    [default: pdf]
  -v, --verbose...                 Log verbosity: -v for debug, -vv for trace
      --pdfa <PDFA>                Export PDF/A at this level instead of plain PDF
      --merge                      Merge all inputs into one PDF
      --asset <ASSETS>             An image, stylesheet or font an HTML page names by file name. Repeat it for each
      --html-engine <HTML_ENGINE>  What turns HTML into PDF: fulgur or libreoffice [default: fulgur]
  -o, --output <OUTPUT>            Output file (one input or --merge), or directory (several inputs)
  -h, --help                       Print help

rusticdoc serve

Run the HTTP service. Settings come from RUSTICDOC_* variables

Usage: rusticdoc serve [OPTIONS]

Options:
      --bind <BIND>  Address to listen on [env: RUSTICDOC_BIND=]
  -v, --verbose...   Log verbosity: -v for debug, -vv for trace
  -h, --help         Print help

rusticdoc openapi

Print the OpenAPI description as JSON

Usage: rusticdoc openapi [OPTIONS]

Options:
  -v, --verbose...  Log verbosity: -v for debug, -vv for trace
  -h, --help        Print help

rusticdoc health

Check a running service, for container health checks. Exits 0 when up

Usage: rusticdoc health [OPTIONS]

Options:
      --url <URL>   The service's address. By default, where this configuration serves
  -v, --verbose...  Log verbosity: -v for debug, -vv for trace
  -h, --help        Print help

rusticdoc engines

Show the engines this machine has

Usage: rusticdoc engines [OPTIONS]

Options:
  -v, --verbose...  Log verbosity: -v for debug, -vv for trace
  -h, --help        Print help

rusticdoc pdf

PDF operations: merge, split, rotate, flatten, optimize, encrypt, metadata, bookmarks, embed, watermark, stamp, sign, factur-x, forms

Usage: rusticdoc pdf [OPTIONS] <COMMAND>

Commands:
  merge      Merge PDFs in the order given
  split      Split by page ranges (`1-3,5`) or into intervals of N pages
  rotate     Rotate pages by 90, 180 or 270 degrees
  flatten    Flatten forms and annotations into the page content
  optimize   Recompress streams and drop unused objects
  encrypt    Encrypt with AES-256
  metadata   Read metadata as JSON, or write keys from a JSON object
  bookmarks  Read the outline as JSON, or replace it from a JSON array
  embed      Attach files to a PDF
  watermark  Put text, an image or a PDF under the page content
  stamp      Put text, an image or a PDF over the page content
  sign       Sign cryptographically with --key and --cert (PAdES B-B to B-LTA, invisible unless --image or --x and --y are given), or, without them, place a signature image at exact coordinates, which is not a cryptographic signature
  facturx    Embed Factur-X invoice XML
  fields     List a form's fields as JSON
  fill       Fill a form from JSON data; tags in annotations are applied too
  overlay    Lay one PDF over another, page by page
  help       Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Log verbosity: -v for debug, -vv for trace
  -h, --help        Print help

rusticdoc pdf merge

Merge PDFs in the order given

Usage: rusticdoc pdf merge [OPTIONS] --output <OUTPUT> [FILES]...

Arguments:
  [FILES]...

Options:
  -o, --output <OUTPUT>
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
  -h, --help             Print help

rusticdoc pdf split

Split by page ranges (`1-3,5`) or into intervals of N pages

Usage: rusticdoc pdf split [OPTIONS] --span <SPAN> <FILE>

Arguments:
  <FILE>

Options:
      --mode <MODE>      `pages` or `intervals` [default: pages]
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
      --span <SPAN>      Ranges for `pages`, a page count for `intervals`
      --unify            One file holding every range instead of one per range
  -o, --output <OUTPUT>  Directory for the parts [default: .]
  -h, --help             Print help

rusticdoc pdf rotate

Rotate pages by 90, 180 or 270 degrees

Usage: rusticdoc pdf rotate [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
      --angle <ANGLE>    [default: 90]
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
      --pages <PAGES>    Page selection such as `1-3,5`; all when empty [default: ""]
  -o, --output <OUTPUT>
  -h, --help             Print help

rusticdoc pdf flatten

Flatten forms and annotations into the page content

Usage: rusticdoc pdf flatten [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
  -o, --output <OUTPUT>
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
  -h, --help             Print help

rusticdoc pdf optimize

Recompress streams and drop unused objects

Usage: rusticdoc pdf optimize [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
  -o, --output <OUTPUT>
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
  -h, --help             Print help

rusticdoc pdf encrypt

Encrypt with AES-256

Usage: rusticdoc pdf encrypt [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
      --user-password <USER_PASSWORD>    [default: ""]
  -v, --verbose...                       Log verbosity: -v for debug, -vv for trace
      --owner-password <OWNER_PASSWORD>
  -o, --output <OUTPUT>
  -h, --help                             Print help

rusticdoc pdf metadata

Read metadata as JSON, or write keys from a JSON object

Usage: rusticdoc pdf metadata [OPTIONS] <FILE>

Arguments:
  <FILE>

Options:
      --set <SET>        JSON object to write, such as `{"Title":"Invoice"}`
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
  -o, --output <OUTPUT>
  -h, --help             Print help

rusticdoc pdf bookmarks

Read the outline as JSON, or replace it from a JSON array

Usage: rusticdoc pdf bookmarks [OPTIONS] <FILE>

Arguments:
  <FILE>

Options:
      --set <SET>        JSON array of `{title, page, children}`
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
  -o, --output <OUTPUT>
  -h, --help             Print help

rusticdoc pdf embed

Attach files to a PDF

Usage: rusticdoc pdf embed [OPTIONS] --output <OUTPUT> <FILE> [ATTACHMENTS]...

Arguments:
  <FILE>
  [ATTACHMENTS]...

Options:
  -o, --output <OUTPUT>
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
  -h, --help             Print help

rusticdoc pdf watermark

Put text, an image or a PDF under the page content

Usage: rusticdoc pdf watermark [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
      --text <TEXT>            Text for a text mark
  -v, --verbose...             Log verbosity: -v for debug, -vv for trace
      --mark <MARK_FILE>       PNG, JPEG or PDF file for an image or PDF mark
      --position <POSITION>    top-left, top-center, top-right, center, bottom-left, bottom-center, bottom-right [default: center]
      --opacity <OPACITY>      [default: 1]
      --rotation <ROTATION>    [default: 0]
      --scale <SCALE>          Relative to the page width, 0 to 1 [default: 0.5]
      --font-size <FONT_SIZE>  [default: 24]
      --colour <COLOUR>        [default: #808080]
      --pages <PAGES>          [default: ""]
  -o, --output <OUTPUT>
  -h, --help                   Print help

rusticdoc pdf stamp

Put text, an image or a PDF over the page content

Usage: rusticdoc pdf stamp [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
      --text <TEXT>            Text for a text mark
  -v, --verbose...             Log verbosity: -v for debug, -vv for trace
      --mark <MARK_FILE>       PNG, JPEG or PDF file for an image or PDF mark
      --position <POSITION>    top-left, top-center, top-right, center, bottom-left, bottom-center, bottom-right [default: center]
      --opacity <OPACITY>      [default: 1]
      --rotation <ROTATION>    [default: 0]
      --scale <SCALE>          Relative to the page width, 0 to 1 [default: 0.5]
      --font-size <FONT_SIZE>  [default: 24]
      --colour <COLOUR>        [default: #808080]
      --pages <PAGES>          [default: ""]
  -o, --output <OUTPUT>
  -h, --help                   Print help

rusticdoc pdf sign

Sign cryptographically with --key and --cert (PAdES B-B to B-LTA, invisible unless --image or --x and --y are given), or, without them, place a signature image at exact coordinates, which is not a cryptographic signature.

--level b-t and above take the timestamp authority from --tsa-url or RUSTICDOC_SIGNING_TSA_*, and every request (timestamps, OCSP, CRLs) follows RUSTICDOC_SIGNING_OUTBOUND_*: private addresses are refused unless RUSTICDOC_SIGNING_OUTBOUND_ALLOW_PRIVATE=true.

Usage: rusticdoc pdf sign [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>


Options:
      --key <KEY>
          PEM private key (PKCS#8, PKCS#1 or SEC1; RSA or ECDSA P-256), or `pkcs11:<label>` for a key on the token RUSTICDOC_PKCS11_MODULE, _TOKEN or _SLOT, and _PIN_FILE or _PIN describe

  -v, --verbose...
          Log verbosity: -v for debug, -vv for trace

      --cert <CERT>
          PEM certificate for --key, then any chain certificates

      --image <IMAGE>
          PNG or JPEG. With --key, the visible appearance of the signature

      --page <PAGE>
          [default: 1]

      --x <X>
          Points from the page's left edge. With --key and no --image, the signature is shown there as text: signer, date and reason

      --y <Y>
          Points from the page's bottom edge

      --width <WIDTH>
          Width in points; default the image's natural size, or 200 for text

      --level <LEVEL>
          PAdES level (with --key): b-b, b-t (RFC 3161 timestamp), b-lt (and OCSP or CRL validation data in a DSS) or b-lta (and a document timestamp). Default RUSTICDOC_SIGNING_LEVEL, or b-b

      --certify <CERTIFY>
          Certify rather than approve (with --key), with DocMDP permission 1 (no changes), 2 (form filling and signing) or 3 (also annotations)

      --tsa-url <TSA_URL>
          The RFC 3161 timestamp authority (with --key), instead of RUSTICDOC_SIGNING_TSA_URL. https, unless RUSTICDOC_SIGNING_TSA_ALLOW_HTTP=true

      --tsa-cert <TSA_CERT>
          PEM certificate the --tsa-url authority signs with, or the CA it chains to, instead of RUSTICDOC_SIGNING_TSA_CERT. Tokens from any other signer are refused

      --reason <REASON>
          Why the document was signed (with --key)

      --location <LOCATION>
          Where it was signed (with --key)

      --contact-info <CONTACT_INFO>
          How to reach the signer (with --key)

      --signer-name <SIGNER_NAME>
          The signer's name as shown; validators read the certificate (with --key)

  -o, --output <OUTPUT>


  -h, --help
          Print help (see a summary with '-h')

rusticdoc pdf facturx

Embed Factur-X invoice XML

Usage: rusticdoc pdf facturx [OPTIONS] --xml <XML> --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
  -v, --verbose...         Log verbosity: -v for debug, -vv for trace
      --xml <XML>
      --profile <PROFILE>  [default: EN16931]
  -o, --output <OUTPUT>
  -h, --help               Print help

rusticdoc pdf fields

List a form's fields as JSON

Usage: rusticdoc pdf fields [OPTIONS] <FILE>

Arguments:
  <FILE>

Options:
  -v, --verbose...  Log verbosity: -v for debug, -vv for trace
  -h, --help        Print help

rusticdoc pdf fill

Fill a form from JSON data; tags in annotations are applied too

Usage: rusticdoc pdf fill [OPTIONS] --data <DATA> --output <OUTPUT> <FILE>

Arguments:
  <FILE>

Options:
  -d, --data <DATA>
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
      --flatten
  -o, --output <OUTPUT>
  -h, --help             Print help

rusticdoc pdf overlay

Lay one PDF over another, page by page

Usage: rusticdoc pdf overlay [OPTIONS] --output <OUTPUT> <BASE> <OVERLAY>

Arguments:
  <BASE>
  <OVERLAY>

Options:
  -o, --output <OUTPUT>
  -v, --verbose...       Log verbosity: -v for debug, -vv for trace
  -h, --help             Print help

rusticdoc validate

Check a template against sample data and list every problem

Usage: rusticdoc validate [OPTIONS] <TEMPLATE>

Arguments:
  <TEMPLATE>

Options:
  -d, --data <DATA>
  -v, --verbose...                   Log verbosity: -v for debug, -vv for trace
      --lang <LANG>                  The language to render in. Each literal key passed to `t` with no translation for it is a warning
      --translations <TRANSLATIONS>  JSON file of translations by language, as the service's `translations` field
  -h, --help                         Print help

rusticdoc translate

Create or update `<lang>.json` with the keys templates pass to `t`. Translations already there are kept, new keys get an empty text, and keys no template uses any more are listed, not removed

Usage: rusticdoc translate [OPTIONS] --lang <LANG> <PATHS>...

Arguments:
  <PATHS>...  Office and text templates, or directories to search for them

Options:
      --lang <LANG>  The language of the dictionary, such as `fr` or `fr-CA`
  -v, --verbose...   Log verbosity: -v for debug, -vv for trace
      --out <OUT>    Where `<lang>.json` is created or updated [default: translations]
  -h, --help         Print help

rusticdoc webhook-secret

Print the key a caller's webhook deliveries are signed with, in hex, from RUSTICDOC_WEBHOOK_SECRET. A receiver decodes it and verifies with it

Usage: rusticdoc webhook-secret [OPTIONS]

Options:
      --api-key <API_KEY>            The caller's API key
  -v, --verbose...                   Log verbosity: -v for debug, -vv for trace
      --basic-user <BASIC_USER>      The caller's basic-auth user
      --oidc-subject <OIDC_SUBJECT>  The subject of the caller's OpenID Connect tokens
      --tenant <TENANT>              The caller's tenant, from RUSTICDOC_TENANT_KEYS: every key of a tenant signs with the same key
  -h, --help                         Print help