Metadata-Version: 2.4
Name: heritage-cli
Version: 1.0.3
Summary: Unified CLI for the heritage science open-source ecosystem — orchestrates HOARD, StratiGraph, Trowel, Libby, Dibble, and other tools
Author-email: Mark Bouck <markbouck@duck.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dig-tools/heritage-cli
Project-URL: Documentation, https://github.com/dig-tools/heritage-cli#readme
Project-URL: Issues, https://github.com/dig-tools/heritage-cli/issues
Project-URL: Repository, https://github.com/dig-tools/heritage-cli.git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: hoard
Requires-Dist: hoard; extra == "hoard"
Provides-Extra: libby
Requires-Dist: libby; extra == "libby"
Provides-Extra: dibble
Requires-Dist: dibble; extra == "dibble"
Provides-Extra: trowel
Requires-Dist: trowel; extra == "trowel"
Provides-Extra: stratigraph
Requires-Dist: stratigraph; extra == "stratigraph"
Dynamic: license-file

<p align="center">
  <img src="docs/brand/project-lockup.svg" alt="Dig:Tools" width="720">
</p>

# heritage-cli

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

[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](#licence)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python)](pyproject.toml)
[![GitHub](https://img.shields.io/badge/GitHub-dig--tools%2Fheritage--cli-181717?logo=github)](https://github.com/dig-tools/heritage-cli)

`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

```bash
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:

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

## Common commands

```bash
# 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`](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

| Repository | Role |
|---|---|
| [Dig:Codex](https://github.com/dig-tools/codex) | Report generation and research/archive tools |
| [Dig:Stratum](https://github.com/dig-tools/stratum) | Field recording and Harris Matrices |
| [Dig:Crucible](https://github.com/dig-tools/crucible) | Lithics, dating, and laboratory analysis |
| [Dig:Folio](https://github.com/dig-tools/folio) | Collections management and vocabulary generation |
| [heritage-types](https://github.com/dig-tools/heritage-types) | Canonical cross-tool schemas |

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

## Development

```bash
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](USER_GUIDE.md) for pipeline setup, review gates, state, and
troubleshooting.

## Licence

MIT.
