CLI Reference

Phi CLI Reference

phi is the command-line interface for the Dyno Phi filtering platform. Upload binder candidate datasets, run the scoring and filtering pipeline, manage jobs, and download results — all from your terminal.

Version: 0.1.0·Package: dyno-phi·Requires: Python ≥ 3.9·GitHub

Installation & authentication

pip install dyno-phi
# or with uv:
uv tool install dyno-phi

Set your API key (obtain from Settings → API keys in the Dyno web app):

export DYNO_API_KEY=ak_...

Verify your connection:

phi login

Global flags

Flag	Default	Description
--poll-interval S	5	Seconds between status-poll requests
--version	—	Print version and exit
--help	—	Show help for any command

State caching

phi caches the most recently used dataset ID and job ID in .phi-state.json in the current directory. You don't need to pass --dataset-id or job_id repeatedly in a session.

phi use d7c3a1b2-...         # set active dataset
phi filter --preset default  # uses cached dataset
phi scores                   # uses cached job from last filter/model run
phi download --out ./results # uses cached job

The footer line printed after every command shows the current active IDs:

Active: dataset [d7c3a1b2-...] · job [cb4553f5-...]

Command index

Command	Aliases	Description
phi login	—	Verify API key and print connection + identity
phi fetch	—	Download a structure from RCSB PDB or AlphaFold DB, crop, optionally upload
phi upload	—	Upload PDB/CIF/FASTA files or a directory → create a dataset
phi use	—	Set the active dataset ID
phi datasets	—	List your datasets
phi dataset	—	Show details for a single dataset
phi ingest-session	—	Check the status of an ingest session
phi folding	esmfold	Fast single-sequence structure prediction (ESMFold)
phi complex_folding	alphafold	Monomer or multimer structure prediction (AlphaFold2)
phi inverse_folding	proteinmpnn	Sequence design via inverse folding (ProteinMPNN)
phi esm2	—	Language model log-likelihood scoring and perplexity
phi boltz	—	Biomolecular complex prediction — proteins, DNA, RNA (Boltz-1)
phi filter	—	Full filter pipeline: inverse folding → folding → complex folding → score
phi status	—	Get the status of a job
phi jobs	—	List recent jobs
phi logs	—	Print log stream URL for a job
phi cancel	—	Cancel a running job
phi scores	—	Display scoring metrics table for a completed filter job
phi download	—	Download output files for a completed job
phi research	—	Run a biological research query with citations
phi notes	—	View accumulated research notes for a dataset
phi tutorial	—	Download example datasets and print a getting-started guide

Detailed reference

Verify your API key and print your identity and connection details.

phi login [--json]

phi login

phi fetch

Download a structure from RCSB PDB or the AlphaFold Database, optionally crop it, save it locally, and optionally upload it to the Dyno cloud.

phi fetch (--pdb ID | --uniprot ID) [crop options] [output options]

Source

Flag	Description
--pdb ID	RCSB PDB ID (e.g. 4ZQK)
--uniprot ID	UniProt accession — downloads from AlphaFold DB (e.g. Q9NZQ7)

Cropping

Flag	Description
--chain CHAIN	Extract a single chain (e.g. A)
--residues START-END	Keep only residues in this range (e.g. 56-290)
--trim-low-confidence PLDDT	Remove residues with pLDDT below this threshold. Typical value: 70

Output

Flag	Description
--out FILE	Output PDB path (default: {ID}[_{chain}].pdb in current dir)
--upload	Upload to Dyno cloud after saving — creates a dataset and prints the GCS URI
--name NAME	Dataset name label when using --upload

phi fetch --pdb 4ZQK --chain A --residues 56-290 --out target.pdb
phi fetch --uniprot Q9NZQ7 --trim-low-confidence 70 --upload
phi fetch --pdb 7XKJ --chain B --upload --name pd-l1-target

phi upload

Upload PDB, CIF, or FASTA files (or a directory) to create a dataset for batch processing.

phi upload [FILE ...] [--dir DIR] [options]

Flag	Description
FILE ...	One or more files to upload (positional)
--dir DIR	Upload all matching files in this directory
--file-type TYPE	Override auto-detected file type: pdb, cif, fasta, csv
--run-id ID	Label for this ingest session
--wait / --no-wait	Poll until dataset is READY (default: wait)

phi upload --dir ./designs/ --file-type pdb
phi upload binder1.pdb binder2.pdb binder3.pdb
phi upload --dir ./designs/ --no-wait

phi use

Set the active dataset ID, saved to .phi-state.json.

phi use d7c3a1b2-4f3e-11ef-9ab7-0242ac120002

phi datasets

phi datasets [--limit N] [--json]

phi dataset

phi dataset DATASET_ID [--json]

phi ingest-session

Check the status of a background ingest session (useful after phi upload --no-wait).

phi ingest-session SESSION_ID [--json]

phi folding / esmfold

Fast single-sequence structure prediction using ESMFold. Runtime: ~1 min per sequence.

phi folding (--fasta FILE | --fasta-str FASTA | --dataset-id ID) [options]

Flag	Default	Description
--fasta FILE	—	FASTA file to submit
--fasta-str FASTA	—	FASTA content as a string (for scripting)
--dataset-id ID	—	Pre-ingested dataset ID (batch mode)
--recycles N	3	Recycling iterations
--no-confidence	—	Skip per-residue pLDDT extraction

phi folding --fasta sequences.fasta
phi folding --dataset-id d7c3a1b2-... --wait --out ./results/
phi folding --fasta-str ">binder1
MKTAYIAKQRQISFVKS..."

phi complex_folding / alphafold

Monomer or multimer structure prediction using AlphaFold2 (ColabFold pipeline). Automatically detects multimer mode from : separators. Runtime: ~8–15 min.

phi complex_folding (--fasta FILE | --fasta-str FASTA | --dataset-id ID) [options]

Flag	Default	Description
--fasta FILE	—	FASTA file — use : as chain separator for multimer
--dataset-id ID	—	Pre-ingested dataset ID (batch mode)
--models 1,2,3	1,2,3	Model numbers to run
--model-type TYPE	auto	auto, ptm, multimer_v1, multimer_v2, multimer_v3
--msa-tool TOOL	mmseqs2	MSA algorithm: mmseqs2 or jackhmmer
--template-mode MODE	none	Template lookup: none or pdb70
--recycles N	6	Recycling iterations
--num-seeds N	3	Number of model seeds
--amber	—	Run AMBER force-field relaxation

phi complex_folding --fasta binder_target.fasta
phi complex_folding --fasta monomer.fasta --amber
phi complex_folding --dataset-id d7c3a1b2-... --wait --out ./af2_results/

phi inverse_folding / proteinmpnn

Design sequences for a protein backbone using ProteinMPNN. Runtime: ~1–2 min.

phi inverse_folding (--pdb FILE | --pdb-gcs URI | --dataset-id ID) [options]

Flag	Default	Description
--pdb FILE	—	PDB structure file
--pdb-gcs URI	—	Cloud storage URI to PDB (gs://…)
--dataset-id ID	—	Pre-ingested dataset ID (batch mode)
--num-sequences N	10	Sequences to design
--temperature T	0.1	Sampling temperature 0–1. Lower = more conservative
--fixed A52,A56	—	Comma-separated residue positions to fix

phi inverse_folding --pdb design.pdb --num-sequences 20
phi inverse_folding --pdb binder.pdb --num-sequences 10 --fixed A52,A56,A63
phi inverse_folding --dataset-id d7c3a1b2-... --num-sequences 4 --wait

phi esm2

Language model scoring with ESM2 — pseudo-log-likelihood (PLL) scores and perplexity for sequence plausibility filtering.

phi esm2 (--fasta FILE | --fasta-str FASTA | --dataset-id ID) [options]

phi esm2 --fasta designed_sequences.fasta --wait

phi boltz

Biomolecular complex structure prediction using Boltz-1 (open-source). Supports proteins, DNA, and RNA.

phi boltz (--fasta FILE | --fasta-str FASTA | --dataset-id ID) [options]

Flag	Default	Description
--recycles N	3	Recycling iterations
--no-msa	—	Disable MSA for faster, lower-accuracy prediction

phi boltz --fasta complex.fasta --wait

phi filter

Run the full binder design validation pipeline on a dataset: ProteinMPNN → ESMFold → AlphaFold2 → scoring.

phi filter [--dataset-id ID] [--preset NAME] [threshold flags] [options]

Preset

Flag	Description
--preset default\|relaxed	Apply a named threshold preset. Individual flags override preset values

Threshold overrides

Flag	Default	Description
--plddt-threshold F	0.80	ESMFold binder pLDDT lower bound
--ptm-threshold F	0.55	AlphaFold2 complex pTM lower bound
--iptm-threshold F	0.50	AlphaFold2 interface pTM lower bound
--ipae-threshold F	10.85 Å	AlphaFold2 interface PAE upper bound
--rmsd-threshold F	3.5 Å	Binder backbone RMSD upper bound

Pipeline options

Flag	Default	Description
--num-sequences N	4	ProteinMPNN sequences per design
--num-recycles N	3	AlphaFold2 recycling iterations
--msa-tool TOOL	single_sequence	single_sequence (recommended for de novo binders), mmseqs2, jackhmmer
--wait	on	Poll until pipeline completes
--out DIR	—	Download results when done
--all	—	When --out is set, download all artifact types

phi filter --preset default --wait
phi filter --dataset-id d7c3a1b2-... --plddt-threshold 0.75 --iptm-threshold 0.45 --wait
phi filter --preset relaxed --wait --out ./results/
phi filter --preset default --wait --out ./results/ --all

phi status

phi status JOB_ID [--json]

phi jobs

Flag	Default	Description
--limit N	20	Number of jobs to show
--status STATUS	—	Filter: pending, running, completed, failed, cancelled
--job-type TYPE	—	Filter by job type (e.g. esmfold, design_pipeline)
--json	—	Print raw JSON

phi jobs
phi jobs --status running
phi jobs --limit 50 --job-type design_pipeline

phi logs

phi logs JOB_ID [--follow]

phi cancel

phi cancel JOB_ID

phi scores

Display the scoring metrics table for a completed filter job.

Flag	Default	Description
JOB_ID	cached	Job ID (default: last cached job)
--top N	20	Show top-N candidates ranked by score
--out FILE	—	Save scores CSV to file
--json	—	Output raw JSON

phi scores
phi scores --top 50 --out scores.csv

phi download

Download all output files for a completed job — structures, scores CSV, and raw score JSONs.

Flag	Default	Description
JOB_ID	cached	Job ID (default: last cached job)
--out DIR	./results	Output directory
--all	—	Download all artifact types including MSA files and archives

phi download --out ./results/
phi download --out ./results/ --all
phi download cb4553f5-... --out ./run-42/

phi research

Run a biological research query against PubMed, UniProt, and PDB. Synthesises a report with citations. Runtime: ~2–5 min.

Flag	Default	Description
--question QUESTION	(required)	Research question (e.g. "What are binding hotspots for PD-L1?")
--target TARGET	—	Protein or gene name to focus the search (e.g. PD-L1, KRAS)
--databases LIST	pubmed,uniprot,pdb	Comma-separated databases to query
--max-papers N	20	Maximum PubMed papers to retrieve
--structures	—	Include related PDB structures in the report
--context-file FILE	—	Path to a prior research.md — prepended as context
--dataset-id ID	—	Associate notes with a dataset and sync to cloud storage
--notes-file FILE	./research.md	Local append-only notes file
--no-save	—	Skip saving the report to the local notes file

phi research --question "What are the known binding hotspots for PD-L1?"

phi research \
  --question "What is the structure and function of EGFR domain III?" \
  --target EGFR --structures --dataset-id d7c3a1b2-...

# Build on a prior research session
phi research \
  --question "Which of these hotspots are most druggable?" \
  --context-file ./research.md

phi notes

phi notes DATASET_ID [--out PATH] [--json]

phi notes d7c3a1b2-... --out ./campaign-notes.md

phi tutorial

Download example datasets from the API and print an interactive getting-started guide. Ideal for first-time users to explore the filtering pipeline with real data.

phi tutorial

Filter presets

phi filter --preset applies a named set of quality-control thresholds across the full validation pipeline. Override any individual threshold alongside a preset.

Metric	default	relaxed	Description
pLDDT	≥ 0.80	≥ 0.80	ESMFold per-residue confidence (0–1)
pTM	≥ 0.55	≥ 0.45	Global TM-score proxy from ESMFold
ipTM	≥ 0.50	≥ 0.50	Interface pTM from AF2 multimer (0–1)
iPAE	≤ 10.85 Å	≤ 12.4 Å	AF2 interface predicted aligned error
RMSD	≤ 3.5 Å	≤ 4.5 Å	Backbone RMSD vs. reference design

phi filter --preset default --plddt-threshold 0.75 --iptm-threshold 0.45

The single_sequence MSA mode (default for phi filter) is recommended for de novo designed binders — they have no natural homologs, so MSA adds noise rather than signal.

Workflows

Filter a batch of binder candidates

The most common workflow — upload your designs and run the full scoring pipeline in one step.

# 1. Upload your binder candidate PDB or FASTA files
phi upload --dir ./designs/ --file-type pdb

# 2. Run the full filter pipeline (ProteinMPNN → ESMFold → AlphaFold2 → score)
phi filter --preset default --wait --out ./results/

# 3. Review ranked scores
phi scores --top 30

Validate a batch of sequences

Run individual pipeline steps when you need custom control — e.g. to reuse existing folded structures.

# Upload FASTA sequences
phi upload sequences.fasta

# Structure prediction
phi folding --dataset-id d7c3a1b2-... --wait

# Score with ESM2
phi esm2 --dataset-id d7c3a1b2-... --wait

# Download results
phi download --out ./validation/

Research-guided filtering campaign

phi research \
  --question "What are the binding hotspots of PD-L1 for therapeutic binders?" \
  --target PD-L1 --structures --dataset-id d7c3a1b2-...

phi notes d7c3a1b2-...