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.
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 aValueErrorthat lists the supported ones.
Flags
--type TYPE: document type.auto(default) classifies the file; the others arecatalog,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--htmlfile in the default browser.--images DIR: folder for the product photos extracted in the catalog view. Default:<file>_imagesnext 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;0prints 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 examplepip install "terbium-parse[anthropic]".--tier TIER: pin the AI tier:haiku,sonnetoropus. Has an effect only with--ai.--version: printterbium 2.0.0and 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:
--typeiscatalogorlookbookand neither--recordsnor a schema other thanproductis given; or--typeisauto, and classification detectscatalog,lookbook,table,deckorunknown.
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;--schemaset to anything other thanproduct;--typeset totransaction,resume,table,deckorunknown;--type autowhen classification detectstransactionorresume.
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
--limitshows, 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,
--jsonwrites 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