heritage-cli

One command-line front door for repeatable Dig:Tools heritage workflows.

heritage-cli orchestrates existing applications; it does not reimplement their analysis. It can run HOARD phases, invoke compatible radiocarbon, lithics, matrix, review, and publishing commands, and execute declarative YAML pipelines with resumable state and explicit human-review gates.

Install

python -m pip install heritage-cli
heritage --version
heritage --help

Install the tools used by your workflow separately. Compatibility extras are available for the historical command packages:

python -m pip install "heritage-cli[hoard,libby,stratigraph,dibble,trowel]"

Common commands

# Inspect discoverable tools
heritage tools

# Discover open archaeological data with provenance retained
heritage open-context "amphora" --details
heritage open-context "amphora" --details --json > comparanda.json

# Run a single HOARD phase or the full pipeline
heritage run --project my_site --phase 0
heritage run --project my_site --auto

# Run a declarative multi-tool workflow
heritage run --project my_site \
  --pipeline pipeline.example.yaml \
  --workspace ./erd_workspace

# Specialist hand-offs
heritage calibrate --project my_site
heritage lithics --project my_site --input ./scans
heritage review --project my_site
heritage matrix --project my_site
heritage publish --project my_site --format docx,pdf

Run heritage COMMAND --help before scripting a command; the installed version’s help is authoritative.

Open Context discovery

heritage open-context is a bounded, read-only connector to Open Context's public JSON-LD API. It does not mirror data or automatically paginate. Geometry is omitted by default; add --include-geometry only when published coordinates are necessary and ethically appropriate. --details retrieves each record's exact Creative Commons licence, creators, project, and persistent identifier at a service-friendly rate below three requests per second.

Open Context's terms, record-level licences, contributor attribution, and archaeological ethics continue to apply to downloaded results. Human-remains- related records are flagged and produce an ethical-use notice.

Pipelines and state

Pipeline YAML describes ordered application steps and review gates. Progress is stored beneath the selected workspace, allowing an interrupted run to resume without silently repeating completed work. pipeline.example.yaml is a minimal working template.

Human gates are intentional. --auto may skip them in pipeline mode and should only be used when the inputs and outputs are independently reviewed elsewhere.

Dig:Tools relationships

Some command adapters retain historical executable names (hoard, libby, dibble, trowel, stratigraph) for compatibility after consolidation.

Development

git clone https://github.com/dig-tools/heritage-cli.git
cd heritage-cli
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest tests -m "not integration"
mypy src

See USER_GUIDE.md for pipeline setup, review gates, state, and troubleshooting.

Licence

MIT.