itol-cli
iTOL(itol.embl.de)命令行工具:注解模板生成 + 本地 lint 校验 + 上传/导出流水线。
设计哲学:设计即数据——注解文件是一等公民的纯文本模板(人/AI 可直接手写),CLI 负责生成、校验、上传、导出闭环。
uv tool install itol-cli # 首推:免 Python 环境(MultiQC 同款推荐)
pip install itol-cli # 或走 pip(发布后)
# 或源码:pip install -e .
10 秒上手
itol doctor # 环境自检(API key/端点存活)
itol templates # 场景模板库
itol gen subfamily groups.tsv # 分组 tsv → TREE_COLORS + COLORSTRIP
itol gen subfamily g.tsv --tree tree.nwk # 顺带自动验亚家族单系
itol lint itol_colorstrip.txt # 本地校验注解文件
itol lint anno.txt --tree tree.nwk # 交叉校验:注解 ID 是否真在树里
itol export 123456789 --format svg -o tree.svg # 导出(免认证)
itol upload tree.tree ann1.txt --project MyProj # 上传(需订阅+key)
itol upload tree.tree ann1.txt --project P --dry-run # 干跑:全校验不真传
itol render 123 --anno a.txt --out f.svg --dry-run # 干跑:校验树可达+注解,不起浏览器
树文件工具(对标 gotree/nwkit/PhyKIT,上 iTOL 前的预处理)
itol tree validate tree.nwk # 校验树文件(括号/重名/负支长/多叉/不可见字符)
itol tree stats tree.nwk # 树统计(叶数/支长/支持度/多叉/树高)
itol tree peek tree.nwk # 终端 ASCII 速览树结构(SSH/CI 无浏览器)
itol tree reroot t.nwk --outgroup A -o rr.nwk # 定根(外群/中点)
itol tree prune t.nwk --keep A,B,C -o p.nwk # 剪枝
itol tree rename t.nwk --map map.tsv -o rn.nwk # 按映射表重命名叶标签
itol tree render tree.nwk -o t.svg # 本地渲染→SVG(零网络/浏览器,离线降级)
工程特性
itol completion bash # 生成 shell 补全脚本(eval "$(itol completion bash)")
itol commands --format json # 机器可读命令目录(llms.txt 素材)
itol learn old_anno.txt -o style.json # 逆向复用:学已有注解的样式
itol learn old.txt --apply new.tsv -o new.txt # 套样式到新数据
错误码公开文档:docs/ERROR_CODES.md(IT001-006 触发条件→修法)。
关键事实(2026-11-02 官方文档+curl 实证)
- 上传/删除需 iTOL 标准订阅 + APIkey(
userInfo.cgi生成;订阅见 pricing.cgi);export ITOL_API_KEY=...或写~/.itol-cli/config - 导出免认证:公开树按数字 ID 即可导出;格式 svg/eps/pdf/png/newick/nexus/phyloxml
- 导出无 dpi/宽高参数——高分辨率位图是缺口,默认用 SVG/PDF/EPS 矢量
- 官方无速率限制,本工具默认串行+1s 间隔+指数退避
- 分享 URL(/tree/<id>)无鉴权,知 ID 即可访问——注意未发表数据
场景模板库
| 场景 | 输入 | 产出 |
|---|---|---|
subfamily 亚家族着色主树 |
分组 tsv(node_id TAB group) | TREE_COLORS + COLORSTRIP(Okabe-Ito/Tol 18 色板) |
bootstrap 支持率展示 |
IQ-TREE .contree | 导出参数预设(≥95 实心点规则) |
heatmap 表达热图联树 |
矩阵 tsv(首列=树叶名) | DATASET_HEATMAP(内建行序=树序校验) |
domains 域结构联树 |
域表 tsv(gene/domain/start/end/len) | DATASET_DOMAINS(官方原生类型) |
motif 基序联树 |
motif 表 tsv(同构) | DATASET_DOMAINS(motif 作色块) |
selection 选择压力标注树 |
ω 表 tsv(node TAB omega) | TREE_COLORS(枝按 ω 蓝→白→红渐变) |
connections 共线连线树/tanglegram |
配对表 tsv(node1 TAB node2 [color] [label]) | DATASET_CONNECTION |
timescale 时间树地质年代轴 |
区间表 tsv(name TAB start TAB end [color]) | DATASET_TIMESCALE |
pav 泛基因组 PAV 联树 |
0/1 矩阵 tsv(首列=树叶名) | DATASET_BINARY |
错误契约
IT001 INVALID_INPUT / IT002 UPLOAD_FAILED / IT003 EXPORT_FAILED / IT004 AUTH_REQUIRED / IT005 RATE_LIMITED / IT006 INTERNAL——每个错误带 retryable 与诊断建议。
License
MIT
Metadata
Release files for itol-cli 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| itol_cli-0.2.0.tar.gz | 55.2 kB | Without provenance | Details for itol_cli-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| itol_cli-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for itol_cli-0.2.0-py3-none-any.whl |
Total release size: 110.3 kB
Release files / itol_cli-0.2.0.tar.gz
| Download URL | itol_cli-0.2.0.tar.gz |
|---|---|
| Size | 55.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8141e52f3c8915b7d3538228f7817237e9c80e94a130f9096ff831fbac0d70d0
|
|
BLAKE2b-256 checksum How to use checksums |
9f6e845a719322bca036bfc1b98a3027354aa696b3ece14ba0fe2d19f81abbb1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / itol_cli-0.2.0-py3-none-any.whl
| Download URL | itol_cli-0.2.0-py3-none-any.whl |
|---|---|
| Size | 55.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98e4008c122125aba32ece61549900aeceea06002f1c479f97f49d15459c5ecd
|
|
BLAKE2b-256 checksum How to use checksums |
62dc9d04311d356a2163cd7e5303705008cad7154f764633c04220ebe1e33216
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for itol-cli 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.