Skip to content
terbium

terbium / Reference

CLI reference

Every flag of the terbium command, how it chooses between the catalog table and the records view, and what it writes.

On this page
  1. Argument
  2. Flags
  3. Which view you get
  4. Output details
  5. Errors and exit status
  6. Examples

The terbium command-line interface (CLI) is installed with the package ([project.scripts] terbium = "terbium.cli:main"). This page describes version 2.0.0, taken from src/terbium/cli.py, which is unchanged since 0.10.0.

The command is a thin layer over two Python functions. It never needs a key, and it chooses between a product table and a records table from the detected document type, because those are the two shapes terbium’s output takes.

terbium [-h] [--type {auto,catalog,lookbook,transaction,resume,table,deck,unknown}]
        [--csv OUT] [--html OUT] [--open] [--images DIR] [--no-images]
        [--limit LIMIT] [--records] [--schema SCHEMA] [--json OUT]
        [--ai] [--tier {haiku,sonnet,opus}] [--version]
        file

Argument

  • file: path to a file with one of these extensions: csv, jpeg, jpg, pdf, png, pptx, tif, tiff, tsv, webp, xlsm, xlsx. Any other extension stops with a ValueError that lists the supported ones.

Flags

  • --type TYPE: document type. auto (default) classifies the file; the others are catalog, lookbook, transaction, resume, table, deck, unknown.
  • --csv OUT: write the output as comma-separated values (CSV) to a path, or to stdout with -.
  • --html OUT: write a self-contained HyperText Markup Language (HTML) table to a path, or to stdout with -.
  • --open: open the --html file in the default browser.
  • --images DIR: folder for the product photos extracted in the catalog view. Default: <file>_images next to the input, for Portable Document Format (PDF) and PowerPoint (PPTX) files only.
  • --no-images: do not extract photos. In the catalog view this also turns off the photo-anchored rows, so rows come from the product table, and a photo lookbook can come back empty.
  • --limit N: rows to print in the terminal. Default 20; 0 prints all.
  • --records: show parsed records instead of the catalog table.
  • --schema NAME: schema for the records view: product, generic, furniture, transaction, resume, or a schema you registered.
  • --json OUT: write the parsed document as JavaScript Object Notation (JSON) to a path, or to stdout with -. Records view only.
  • --ai: opt in to the artificial intelligence (AI) lane, using provider keys from the environment. Off by default. The provider’s package must be installed, for example pip install "terbium-parse[anthropic]".
  • --tier TIER: pin the AI tier: haiku, sonnet or opus. Has an effect only with --ai.
  • --version: print terbium 2.0.0 and exit.

Which view you get

The command has two views.

The catalog table runs build_catalog and prints the columns SKU, Name, Materials/Ingredients, Dimensions, Image and Page, where SKU is the stock keeping unit code. You get it when:

  • --type is catalog or lookbook and neither --records nor a schema other than product is given; or
  • --type is auto, and classification detects catalog, lookbook, table, deck or unknown.

The records view runs parse and prints one row per record, with sku, confidence and every field as columns. You get it in every other case, including:

  • --records;
  • --schema set to anything other than product;
  • --type set to transaction, resume, table, deck or unknown;
  • --type auto when classification detects transaction or resume.

In the records view, when you do not pass --schema, catalog, lookbook and table use the product schema and the other types use the schema that parse picks for them.

Output details

  • The catalog view prints a header line such as terbium 2.0.0 · catalogue.pdf · 124 products · images -> catalogue_images/.
  • The records view prints terbium 2.0.0 · <source kind> · <document type> · <n> records.
  • When more rows exist than --limit shows, a final line says how many more there are.
  • File writes are confirmed on stderr, for example wrote 124 products -> out.csv.
  • In the catalog view, --csv - prints only the CSV and exits. In the records view, --csv - prints the CSV and then the terminal table.
  • In the records view, --json writes the JSON and exits without writing CSV or HTML.
  • Escalation messages go to stderr (see Confidence and escalation).
  • With --type auto, the catalog view reads the file once to classify it and again to build the table.

Errors and exit status

The command returns 0 on success. A bad --type or --tier value is caught by the argument parser, which prints the valid choices and exits with status 2. Other problems, such as an unsupported extension, a missing file or an unknown --schema name, end in a Python traceback whose last line names the problem, and the exit status is 1:

ValueError: terbium has no adapter for '.docx'. Supported: csv, jpeg, jpg, pdf, png, pptx, tif, tiff, tsv, webp, xlsm, xlsx.
ValueError: unknown schema 'bogus'. Available: furniture, generic, product, resume, transaction.

Examples

terbium catalogue.pdf                        # catalog table, photos to catalogue_images/
terbium catalogue.pdf --csv out.csv --limit 0
terbium lookbook.pdf --images out/           # choose where photos go
terbium prices.xlsx --no-images
terbium catalogue.pdf --records --schema furniture
terbium report.xlsx --records --json out.json
terbium invoice.pdf --type transaction --csv invoice.csv
terbium resume.pdf --type resume --html resume.html --open
terbium deck.pptx --ai --tier opus
terbium scan.png                             # needs Tesseract for text