# genome.sh full context

> Complete machine-readable context for genome.sh, an open-source genetic variant CLI and API.

Last updated: 2026-09-04

## Product facts

- Name: genome.sh
- Tagline: The jq of genomics
- Install: `cargo install genome-sh`
- Binary: `genome`
- License: MIT
- Language: Rust CLI, Nuxt 3 website
- Databases: ClinVar, gnomAD, dbSNP, AlphaMissense, ClinGen, PharmGKB, UniProt
- Website: https://genome.sh/
- HTTP API: https://api.genome.sh
- Crate: https://crates.io/crates/genome-sh
- CLI source: https://github.com/romainsimon/genome-sh
- Website source: https://github.com/romainsimon/genome.sh

## What it is

genome.sh is a local CLI and REST API for querying genetic variants. People use it to look up rsIDs, annotate a VCF, and produce a private printable DNA report from a file that never leaves their machine.

## What it is not

- Not a medical device
- Not a replacement for clinical sequencing or genetic counseling
- Not a place to upload raw DNA for cloud analysis
- Not AlphaGenome itself. AlphaGenome prediction is an optional, key-gated CLI command

## Local analysis

`genome db install` downloads annotation databases to disk. Queries then run against local SQLite. Private sample files never need to leave the machine. Browser import at https://genome.sh/import also parses VCF in the browser; it does not upload the file to genome.sh.

## HTTP API

| 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. |

Query values: `rs1799945`, `BRCA1`, `chr6:26090951`, `chr6:26090951:C:G`, or HGVS such as `NM_000410.4:c.187C>G`.

## CLI

- `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.

## Agent report contract

Produce a private, printable DNA analysis PDF for the person who is asking, using the genome.sh CLI on their local machine. Do the work, not a plan.

The deliverable is an A4 PDF report filled from their own DNA file (VCF, 23andMe, Ancestry, MyHeritage, or similar). It should match the genome.sh printable report: cover, methodology, five takeaways, domain dashboard, then heart, cancer, longevity, metabolism, immune, brain, physical traits, pharmacogenomics, recommendations, limits, and glossary. Optional extra panels: polygenic scores and trait grid when the file supports them.

1. Privacy

Keep the raw DNA file, intermediate TSV/JSON, filled HTML, and PDF on the user's machine. Never upload genomes to genome.sh, to https://api.genome.sh, or to any third party. Do not commit filled reports. Copy the template out of the repo before writing personal data:

```sh
cp -R docs/report-template ~/my-genome-report
cd ~/my-genome-report
```

Template and PDF helper: https://github.com/romainsimon/genome-sh/tree/main/docs/report-template

2. Analyse locally with genome

Install with `cargo install genome-sh` (or `conda install -c bioconda genome-sh`). The binary is `genome`.

```sh
genome db install standard
genome db status
genome query rs1799945 --format json
genome annotate INPUT.vcf.gz --format json
genome annotate INPUT.vcf.gz --filter clinical --format json
```

Use `standard` (or `full`) so ClinVar and gnomAD frequencies are available. Prefer `--format json` or `compact` for your own scripts. If the input is a consumer chip export, convert or parse it to genotypes first, then query the rsIDs that are actually present. State the assay type, SNP count, and reference build in the methodology section.

3. What the report must contain

Copy `report.html` and `generate-pdf.sh` from the template. Replace every `{{PLACEHOLDER}}`. Use status pills `favorable`, `watch`, `action`, or `neutral`. Keep the A4 print CSS.

Required narrative:
- Cover: name only if the user supplied it, date, sequencing source, tools (`genome` + ClinVar/gnomAD/PharmGKB).
- Methodology: chip vs whole-genome limits, missing major markers, sex chromosomes if known. A SNP chip is not a full BRCA screen.
- Five takeaways a non-specialist can act on or understand.
- Dashboard one-liners by domain.
- Domain findings with rsID, genotype, ClinVar significance, condition, and population frequency when returned.
- Pharmacogenomic card for drug-metabolism genes that were actually called.
- Recommendations split by strength, each tied to a finding.
- Limits and glossary.
- Medical disclaimer: informational, not a diagnosis, not a medical device.

4. Evidence rules

- Do not invent pathogenicity, frequencies, or gene-disease links. Use what `genome query` / `genome annotate` returns.
- If a famous marker is absent from the file (for example APOE ε4, a CYP star allele, or a founder BRCA variant), write "not called" instead of assuming wild type.
- Distinguish heterozygous, homozygous reference, and homozygous alternate.
- Chip files miss rare variants. Say so. Do not claim "no BRCA risk" from a few founder SNPs.
- AlphaGenome prediction is opt-in and sends sequence off-machine. Skip it unless the user explicitly asks.

5. Render the PDF

Fill `report.html`, then:

```sh
./generate-pdf.sh report.html report.pdf
```

Confirm no `{{PLACEHOLDER}}` remains. Open or list the PDF path. Tell the user where the private folder is and that it should stay off git.

Canonical documentation:
- https://genome.sh/docs/agent-guide.md
- https://genome.sh/llms.txt
- https://genome.sh/genome-catalog.json
- https://github.com/romainsimon/genome-sh/tree/main/docs/report-template
- https://crates.io/crates/genome-sh
- https://github.com/romainsimon/genome-sh

## Canonical resources

- Agent guide: https://genome.sh/docs/agent-guide
- Agent guide (markdown): https://genome.sh/docs/agent-guide.md
- Prompt: https://genome.sh/agent-prompt.txt
- Catalog: https://genome.sh/genome-catalog.json
- LLM index: https://genome.sh/llms.txt
- Docs: https://genome.sh/docs