# genome.sh agent report guide

> Use this guide when a coding agent should analyse a local DNA file with genome.sh and produce a private A4 PDF report. It is written for coding agents and humans.

Last updated: 2026-09-04

## Goal

Turn a VCF or consumer DNA export into a narrative printable report. The agent runs `genome` on the user's machine, fills the HTML template, and renders PDF. It does not integrate genome.sh into another product, and it does not upload genomes.

## Privacy boundary

| Data | Where it may go |
| --- | --- |
| rsID, gene symbol, HGVS, genomic coordinates | HTTP API, website query, local CLI |
| VCF / BAM / CRAM / 23andMe / Ancestry / MyHeritage files | Local `genome` CLI only |
| Filled report HTML and PDF | Local folder only, never committed |
| AlphaGenome prediction requests | Opt-in, API-key gated, with an explicit warning |

Never upload raw genomic files to https://genome.sh or https://api.genome.sh. Copy the template to a private directory before writing personal data.

## Report template

Source: https://github.com/romainsimon/genome-sh/tree/main/docs/report-template

```sh
cp -R docs/report-template ~/my-genome-report
cd ~/my-genome-report
# fill report.html, then:
./generate-pdf.sh report.html report.pdf
```

Sections: about, methodology, five takeaways, dashboard, heart, cancer, longevity, metabolism, immune, brain, physical traits, pharmacogenomics, recommendations, limits, glossary. Optional polygenic-score and trait panels when the file supports them. Status pills: `favorable`, `watch`, `action`, `neutral`.

## Install

```sh
cargo install genome-sh
genome db install standard
genome db status
```

Alternative: `conda install -c bioconda genome-sh`. The crate is `genome-sh`. The binary is `genome`. Prefer `standard` or `full` for a personal report so gnomAD frequencies are available.

## CLI contract

- `genome query`: Look up variants by rsID, coordinates, HGVS, or gene.
- `genome annotate`: Annotate a VCF against the local database, streaming record by record.
- `genome compare`: Compare two genomes for shared, unique, and clinically significant variants.
- `genome extract`: Extract variants from CRAM or BAM files.
- `genome predict`: Opt-in AlphaGenome effect prediction. Requires an API key and explicit consent.
- `genome db`: Install, update, and inspect the local variant database.
- `genome config`: Set default format, reference genome, and optional AlphaGenome key.

Examples:

```sh
genome query rs1799945 --format json
genome query BRCA1 --format json
genome annotate input.vcf.gz --filter clinical --format json
```

Formats: `human` (default), `json`, `compact`. Agent scripts should use `--format json`.

## Evidence and medical limits

- Do not invent ClinVar significance or frequencies.
- Missing markers are "not called", not wild type.
- A genotyping chip is not whole-genome sequencing and is not a complete BRCA test.
- The PDF is informational, not a medical device or a diagnosis.

## HTTP API (public identifiers only)

Base URL: https://api.genome.sh

No authentication. Do not send raw genomes here.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/query/:query` | Look up variants by rsID, gene name, genomic coordinates, or HGVS notation. |
| `GET` | `/v1/gene/:gene` | List known variants for a gene symbol such as BRCA1. |
| `GET` | `/v1/gnomad/:rsid` | Fetch gnomAD population frequencies for an rsID. |
| `GET` | `/v1/sources` | List bundled annotation sources and versions. |
| `GET` | `/v1/stats` | Return database counts and pipeline freshness. |
| `GET` | `/v1/health` | Health check for the HTTP API. |

## Copy-ready coding-agent prompt

Copy the canonical prompt from [https://genome.sh/agent-prompt.txt](https://genome.sh/agent-prompt.txt).

## Machine-readable references

- LLM index: https://genome.sh/llms.txt
- Full LLM context: https://genome.sh/llms-full.txt
- Catalog: https://genome.sh/genome-catalog.json
- Report template: https://github.com/romainsimon/genome-sh/tree/main/docs/report-template
- Human docs: https://genome.sh/docs
- Crate: https://crates.io/crates/genome-sh
- CLI source: https://github.com/romainsimon/genome-sh

## License

MIT. Attribution is appreciated but not required.