Metadata-Version: 2.4
Name: orthodb-cli
Version: 0.1.1
Summary: Agent-friendly CLI for cached OrthoDB downloads and live API queries.
Author: Gustavo Madeira Santana
License-Expression: MIT
Project-URL: Homepage, https://github.com/gumadeiras/orthodb-cli
Project-URL: Repository, https://github.com/gumadeiras/orthodb-cli
Project-URL: Issues, https://github.com/gumadeiras/orthodb-cli/issues
Keywords: orthodb,orthologs,bioinformatics,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: release
Requires-Dist: build>=1.2.2; extra == "release"
Requires-Dist: twine>=6.1.0; extra == "release"
Dynamic: license-file

# orthodb-cli

Agent-friendly CLI for OrthoDB v12.

Repo:

```text
https://github.com/gumadeiras/orthodb-cli
```

Goals:

- cache official OrthoDB flat files locally with checksums
- answer common lookups from cached data when available
- fall back to the live OrthoDB URL API when local data is missing or too large
- emit machine-readable JSON by default for API responses and cache metadata
- stay easy to package for Homebrew

## Install

Homebrew:

```bash
brew tap gumadeiras/tap
brew install orthodb-cli
```

From source:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
```

## Examples

```bash
orthodb version
orthodb search p450 --level 33208 --singlecopy 0.8 --take 2
orthodb group 4977at9604
orthodb orthologs 4977at9604 --species 9606_0,10090_0
orthodb fasta 4977at9604 --species 9606_0 --output group.fa
orthodb cache manifest
orthodb cache download species
orthodb cache plan orthologs
orthodb cache index species
orthodb cache sync minimal --index
orthodb resolve 4977at9604
orthodb local species "Homo sapiens"
orthodb local og "olfactory"
orthodb export ogs --query "olfactory receptor" --limit 10
```

`/blast`, `/fasta`, and `/tab` calls are rate-limited to one request per
second, matching OrthoDB's published API guidance.

## Cache

Default cache root:

```text
$XDG_CACHE_HOME/orthodb-cli
```

or:

```text
~/.cache/orthodb-cli
```

Override with:

```bash
orthodb --cache-dir /path/to/cache cache status
```

The flat-file manifest is read from:

```text
https://data.orthodb.org/current/download/odb_data_dump
```

Large data files are intentionally not auto-downloaded. Use
`orthodb cache manifest` first, then download a named dataset.

Curated sync profiles:

- `minimal`: species, levels, level-to-species
- `annotations`: minimal metadata plus OG annotations
- `orthologs`: OG tables, skipping multi-GB files unless `--include-large`

Build a local SQLite index from downloaded files:

```bash
orthodb cache index all
orthodb cache db
```

Indexed local queries:

```bash
orthodb local species "Homo sapiens"
orthodb local og "Cytochrome P450"
orthodb local gene P12345
orthodb local orthologs 4977at9604
orthodb export species --query "Homo sapiens" --limit 2
```

`export` emits newline-delimited JSON from the local SQLite index, capped by
`--limit`.

Resolve IDs before choosing a query path:

```bash
orthodb resolve 4977at9604
orthodb resolve 9606_0:0017fc
orthodb resolve P12345
```

## Release

Current release: `v0.1.1`.

Release artifacts are attached to GitHub releases for Homebrew packaging:

```text
https://github.com/gumadeiras/orthodb-cli/releases
```

## Source Notes

Primary references:

- OrthoDB v12 user guide and URL API: <https://www.ezlab.org/orthodb_v12_userguide.html#api>
- OrthoDB current flat files: <https://data.orthodb.org/current/download/odb_data_dump>
- OrthoDB-py: <https://gitlab.com/ezlab/orthodb_py>

The official Python package is useful reference material, but this CLI uses
direct HTTP calls and local flat files for a smaller runtime surface and simpler
Homebrew packaging.
