Metadata-Version: 2.4
Name: seashell-cli
Version: 0.1.6
Summary: Seashell — Genomic data, compressed and queryable
License: Proprietary
Project-URL: Homepage, https://seashell.bio
Project-URL: Documentation, https://seashell.bio/docs
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# Seashell CLI

Command-line tool for querying and managing genomic data on Seashell.

## Install

```bash
pip install seashell-cli
```

## Quick Start

```bash
seashell
```

You'll be prompted for your API key (from your institution admin), username, and password. After login, you're in an interactive shell. Every example below is typed directly at the `seashell>` prompt — copy any line and paste it.

```
LIST PATIENTS
FIND VARIANTS WHERE patient=NA12878 AND gene=BRCA1
EXPORT PATIENT NA12878 FORMAT CRAM
```

## Single Query Mode

For one-off queries from a shell script, pass the query as a string argument:

```bash
seashell "FIND PATIENTS WHERE gene=BRCA1 AND significance=pathogenic"
seashell "COUNT VARIANTS WHERE patient=NA12878"
seashell --format json "LIST PATIENTS"
```

## Commands

| Command | Description |
|---|---|
### Variant queries
| Command | Description |
|---|---|
| `LIST PATIENTS` | List all patients in your institution |
| `LIST GENES` | List all gene symbols |
| `COUNT VARIANTS WHERE patient=NA12878` | Count a patient's variants (sub-millisecond) |
| `COUNT PATIENTS WHERE gene=BRCA1` | Count patients matching criteria |
| `FIND VARIANTS WHERE patient=NA12878 AND gene=BRCA1` | Variants in a gene for one patient |
| `FIND PATIENTS WHERE gene=BRCA1 AND significance=pathogenic` | Carriers of a variant |
| `FIND SIMILAR TO patient=NA12878` | Genetically similar patients |
| `COMPARE PATIENTS NA12878 AND HG00096` | Jaccard similarity between two patients |
| `DIFF PATIENTS NA12878 AND HG00096` | Exact variant differences |
| `PCA PATIENTS` | Principal component analysis |

### Sequencing QC (drop-in replacements for samtools / Picard / FastQC)
| Command | Replaces | Notes |
|---|---|---|
| `COVERAGE PATIENT id REGION chr:start-end` | `samtools depth -r ...` | Mean depth + % above 10x/20x/30x |
| `QC PATIENT id` | `samtools flagstat` + `samtools stats` | Combined read-stats summary |
| `FLAGSTAT PATIENT id` | `samtools flagstat` | **Byte-identical** 16-line output (md5 verified) |
| `INSERT_SIZE PATIENT id` | `samtools stats` IS / Picard CISM | **Byte-identical** mean & std + Picard-style percentiles |
| `CYCLE_QUALITY PATIENT id` | Picard `MeanQualityByCycle` / FastQC | Per-cycle base quality decay — **constant time**, zero decode |
| `PILEUP PATIENT id POSITION chr:pos` | `samtools mpileup` | Per-base pileup at one position |

### Family genetics & cohort QC (drop-in replacements for peddy / KING / verifyBamID2 / ADMIXTURE)
| Command | Replaces | Notes |
|---|---|---|
| `SEXCHECK PATIENT id` | `peddy --plot` sex check | Infer biological sex from chrX/chrY normalized coverage |
| `KINSHIP COHORT [UNEXPECTED] [LIMIT N]` | `KING --kinship` / `peddy` | Pairwise sketch-Jaccard pre-screen, ~5 µs per pair |
| `KINSHIP TRIO mom dad child` | `peddy` trio mode | Validate a declared family with sample-swap warnings |
| `CONTAMINATION PATIENT id` | `verifyBamID2` | Sample-swap and contamination pre-screen (LoD ~3-5%) |
| `ANCESTRY PATIENT id` | `ADMIXTURE` / `peddy ancestry` | Predict super-population (EUR/EAS/SAS/AFR/AMR) — **100% accuracy** on the 1000G validation set |
| `MENDELIAN TRIO mom dad child` | `bcftools +mendelian` / DeNovoGear | De novo + inheritance partition for a trio |

### Data management
| Command | Description |
|---|---|
| `UPLOAD PATIENT id CRAM s3://path.cram VCF s3://path.vcf.gz` | Upload pre-aligned CRAM/BAM |
| `UPLOAD PATIENT id FASTQ s3://R1.fastq.gz s3://R2.fastq.gz` | Upload raw FASTQ |
| `UPLOAD BATCH s3://manifest.json` | Batch upload from manifest |
| `EXPORT PATIENT id FORMAT CRAM` | Export as CRAM (or BAM) |
| `DELETE PATIENT id` | Remove a patient (admin only) |
| `help` | Show all commands |

## Requirements

- Python 3.8+
- A Seashell API key (contact your institution admin)

## Documentation

https://seashell.bio/docs
