gget
Queries 20+ bioinformatics databases and analysis services through the gget CLI and Python package, covering Ensembl gene search, info and sequences (ref, search, info, seq), BLAST, BLAT, MUSCLE, DIAMOND, PDB, AlphaFold, ELM, ARCHS4, CELLxGENE, Enrichr, Bgee, OpenTargets, cBioPortal, COSMIC, viral sequence downloads (virus), and 8cube mouse specificity and expression data. Use when looking up gene or transcript details, running a quick BLAST/BLAT search, fetching AlphaFold or PDB structures, running enrichment analysis on a gene list, downloading viral sequences with filters, or exploring disease and drug associations interactively. Not for batch processing or fine-grained BLAST control (use biopython) or multi-database Python pipelines (use bioservices).
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill ggetuvx research-agent-skills install ggetDocumentation & Instructions
gget
Overview
gget is a command-line bioinformatics tool and Python package providing unified access to 20+ genomic databases and analysis methods. Query gene information, sequence analysis, protein structures, viral sequences, expression data, disease associations, and mouse tissue/cell specificity metrics through a consistent interface. Most gget modules work both as command-line tools and as Python functions.
Important: The databases queried by gget are continuously updated, which sometimes changes their structure. Guidance here targets gget 0.30.5 (PyPI current as of 2026-06-07). For reproducible work, pin gget==0.30.5; for broken upstream database adapters, update gget after checking release notes.
Installation
Install gget in a clean virtual environment to avoid conflicts:
# Reproducible install targeting this skill
uv venv .venv
source .venv/bin/activate
uv pip install "gget==0.30.5"
# In Python/Jupyter
import gget
Quick Start
Basic usage pattern for all modules:
# Command-line
gget <module> [arguments] [options]
# Python
gget.module(arguments, options)
Most modules return:
- Command-line: JSON (default) or CSV with
-csvflag - Python: DataFrame or dictionary
Common flags across modules:
-o/--out: Save results to file-q/--quiet: Suppress progress information-csv: Return CSV format (command-line only)
Python argument names generally match long CLI options without leading dashes. For example, --census_version becomes census_version=.... Use gget <module> --help for the exact current signature.
Module Categories
gget exposes 23 modules in six categories. Parameters, CLI and Python examples, and return shapes for every one are in references/module_catalog.md; fuller per-parameter documentation is in references/module_reference.md.
| Category | Modules |
|---|---|
| 1. Reference & gene information | ref (Ensembl reference downloads), search (gene search), info (gene/transcript detail), seq (nucleotide and protein sequences) |
| 2. Sequence analysis & alignment | blast, blat, muscle (multiple alignment), diamond (local alignment) |
| 3. Structural & protein analysis | pdb (structures and metadata), alphafold (structure prediction), elm (linear motifs) |
| 4. Expression & disease data | archs4 (correlation, tissue expression), cellxgene (single-cell), enrichr (enrichment), bgee (orthology and expression), opentargets (disease and drug), cbio (cancer genomics), cosmic (mutations) |
| 5. Viral & mouse specificity | virus (viral sequences), 8cube (mouse specificity and expression) |
| 6. Additional tools | mutate (mutated sequences), gpt (text generation), setup (install module dependencies) |
Several modules need a one-time gget setup before first use (alphafold, elm,
cellxgene), and cosmic prompts for COSMIC credentials to download its database.
Common Workflows
Worked multi-module pipelines — gene characterization, structural comparison, expression and enrichment analysis, disease and drug association, orthology comparison, and reference-file preparation for kallisto or alignment — are in references/common_workflows.md, with longer versions in references/workflows.md.
Best Practices
Data Retrieval
- Use
--limitto control result sizes for large queries - Save results with
-o/--outfor reproducibility - Check database versions/releases for consistency across analyses
- Use
--quietin production scripts to reduce output
Sequence Analysis
- For BLAST/BLAT, start with default parameters, then adjust sensitivity
- Use
gget diamondwith--threadsfor faster local alignment - Save DIAMOND databases with
--diamond_dbfor repeated queries - For multiple sequence alignment, use
-s5/--super5for large datasets
Expression and Disease Data
- Gene symbols are case-sensitive in cellxgene (e.g., 'PAX7' vs 'Pax7')
- Run
gget setupbefore first use of alphafold, cellxgene, elm, gpt - For enrichment analysis, use database shortcuts for convenience
- Cache cBioPortal data with
-ddto avoid repeated downloads - For OpenTargets, inspect returned column names before writing filters; gget 0.30.5 follows the newer OpenTargets API schema
Structure Prediction
- AlphaFold multimer predictions: use
-mr 20for higher accuracy - Use
-rflag for AMBER relaxation of final structures - Visualize results in Python with
plot=True - Check PDB database first before running AlphaFold predictions
Viral Data
- Use restrictive filters with
gget virusbefore requesting broad viral datasets - Keep
command_summary.txtwith downstream results for reproducibility and recovery after partial downloads - Use
--baselineand--merge-resultsto resume interrupted viral metadata/sequence downloads
Error Handling
- Database structures change; when an adapter breaks, check upstream release notes and pin the newer fixed version explicitly
- Pin the known-good version for reproducible environments:
uv pip install "gget==0.30.5" - Process max ~1000 Ensembl IDs at once with gget info
- For large-scale analyses, implement rate limiting for API queries
- Use virtual environments to avoid dependency conflicts
- Keep COSMIC and OpenAI credentials in named environment variables or interactive prompts; do not write real credentials into examples, notebooks, or logs
Output Formats
Command-line
- Default: JSON
- CSV: Add
-csvflag - FASTA: gget seq, gget mutate
- PDB: gget pdb, gget alphafold
- PNG: gget cbio plot
- FASTA/CSV/JSONL folder: gget virus
Python
- Default: DataFrame or dictionary
- JSON: Add
json=Trueparameter - Save to file: Add
save=Trueor specifyout="filename" - AnnData: gget cellxgene
- DataFrame/JSON: gget 8cube specificity, psi_block, expression
Resources
This skill includes reference documentation for detailed module information:
references/
module_reference.md- Comprehensive parameter reference for all modulesdatabase_info.md- Information about queried databases and their update frequenciesworkflows.md- Extended workflow examples and use cases
For additional help:
- Official documentation: https://pachterlab.github.io/gget/
- GitHub issues: https://github.com/pachterlab/gget/issues
- Citation: Luebbert, L. & Pachter, L. (2023). Efficient querying of genomic reference databases with gget. Bioinformatics. https://doi.org/10.1093/bioinformatics/btac836
Agent operating procedure
- Check the environment. Confirm network access, API keys (if required) and the database's current API documentation and rate limits.
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Fetch a single known record and check the response format before bulk queries.
- Execute the full task using the instructions and references above.
- Validate the result. Identifiers resolve, record counts are reported, and the database version or access date is recorded.
- Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| HTTP 429 or 5xx errors | Respect rate limits with backoff, batch requests, and report partial results honestly. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- Never invent accession numbers, IDs or records; report 'not found' instead.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Related skills
biopython: Provides Biopython (Bio.Seq, Bio.SeqIO, Bio.Align, Bio.Entrez, Bio.Blast, Bio.PDB, Bio.Phylo, Bio.motifs, Bio.SeqUtils, Bio.Restriction) fo…bioservices: Unified Python interface to 40+ bioinformatics services.pathway-enrichment: Run pathway and gene-set enrichment analysis on gene lists or ranked gene data, then interpret the results.
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects gget for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“quick blast of this protein sequence against nr: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ”
expects Uses gget blast (CLI or Python) with the sequence, sets or confirms program/database (blastp, nr) and a limit, runs a small query first, and reports the top hits with the command and parameters. Does not invent hit accessions or results.
- should trigger
“I have a list of 150 differentially expressed genes from my mouse liver RNA-seq in de_genes.txt (gene symbols). I'm on a cluster node with pip. Can you run GO biological process and KEGG enrichment on them directly from the terminal and save a CSV? I'd also like to see the top 10 terms.”
expects Uses gget enrichr with the correct species flag (mouse) and database shortcuts (e.g. ontology/pathway for GO BP and KEGG), passes the gene symbols from the file, outputs CSV with -csv/-o, and displays the top 10 rows. Notes the gget version and database access date, and that network access is required.
- should trigger
“I'm studying a possible drug target, EGFR. What diseases and drugs are linked to it, and is there a predicted or experimental 3D structure I could look at?”
expects Uses gget opentargets (diseases and drugs resources) for EGFR after resolving the Ensembl ID via gget search/info, and gget pdb and/or gget alphafold for structures, checking PDB first. Inspects returned column names, reports versions and limits, and does not fabricate associations or IDs.
Near misses (2)
- near miss
“I have 300 FASTA files of sequencing contigs and need to run BLAST locally on all of them with custom e-value and word size settings, then parse the XML output into a table with Bio.Blast.”
expects Recognises this as batch processing with fine-grained BLAST control, which belongs to biopython (Bio.Blast and Bio.SeqIO) rather than gget, and recommends that approach with local BLAST+ and XML parsing.
- near miss
“I need to map UniProt IDs to KEGG pathways and ChEMBL targets for 2,000 proteins in one Python pipeline, with retries and caching.”
expects Recognises this as a multi-database ID-mapping pipeline suited to bioservices (UniProt, KEGG, ChEMBL clients) rather than gget's quick single-lookups, and proposes that approach.