ApherisFold CLI

Command-line interface for submitting and managing prediction, benchmark, and fine-tuning workflows on an Apheris Hub instance.

Requirements

• Python 3.10 or later
• Access to an Apheris Hub instance

Installation

conda

Recommended if you already use conda for scientific Python work. A dedicated environment avoids dependency conflicts.

Linux / macOS

conda create -n apherisfold python=3.11 -y
conda activate apherisfold
pip install apherisfold-cli

Windows (Anaconda Prompt or PowerShell)

conda create -n apherisfold python=3.11 -y
conda activate apherisfold
pip install apherisfold-cli

Activate the environment at the start of each session with conda activate apherisfold.

venv (standard Python)

Linux / macOS (venv)

python3 -m venv ~/.venvs/apherisfold
source ~/.venvs/apherisfold/bin/activate
pip install apherisfold-cli

Windows (PowerShell, venv)

python -m venv $env:USERPROFILE\.venvs\apherisfold
& $env:USERPROFILE\.venvs\apherisfold\Scripts\Activate.ps1
pip install apherisfold-cli

Activate the environment at the start of each session with the activate command above.

Verify

apherisfold --version
apherisfold --help

Upgrade

pip install --upgrade apherisfold-cli

Quick start

# Log in with your ApherisFold Hub URL
apherisfold login --url https://hub.example.com

# See available models and weights
apherisfold weights list

# Submit a prediction
apherisfold workflow predict run \
  --model openfold3 \
  --weight 3.0.0 \
  --input ./request.json

# By default, local artifacts are written under ./.apherisfold/runs/<workflow>/<id>
# relative to the directory where you run the command. Use --output to choose another directory.

# List submitted jobs
apherisfold workflow predict list

# Inspect a job
apherisfold workflow predict get --id job_NUlyMsnWq

# Print diagnostics, or save them under ./.apherisfold/runs/predict/<job-id>/logs
apherisfold workflow predict logs --id job_NUlyMsnWq
apherisfold workflow predict logs --id job_NUlyMsnWq --save
apherisfold workflow predict error --id job_NUlyMsnWq --output ./diagnostics

Workflows

Affinity prediction

When using weights that support affinity prediction, the CLI selects the ligand chain automatically if there is only one. For queries with multiple ligand chains, specify which one to score with --affinity-ligand:

apherisfold workflow predict run \
  --model openfold3 \
  --weight 3.0.0 \
  --input ./request.json \
  --affinity-ligand B

Supplying MSAs

Pass precomputed alignments with --asset. A3Ms are matched to structure chains by sequence (an X in the MSA sequence acts as a wildcard), so filenames need not match the structure. Supply one A3M per chain — a single A3M matching several identical chains (for example a homomultimer) is applied to all of them. Chains without a supplied match fall back to automatic MSA generation, and the CLI warns which chains that affects.

# One A3M per chain, matched by sequence
apherisfold workflow predict run \
  --model openfold3 --weight 3.0.0 \
  --input ./complex.cif \
  --asset ./chain-A.a3m --asset ./chain-B.a3m

To disambiguate which structure an A3M belongs to, scope it with a structureId= prefix (queryId= for predict). This narrows the candidate chains to that one structure:

For predict requests supplied as JSON, queryId=path.a3m also uploads the local file under the MSA filename referenced by that query. This is useful when the local filename does not match the JSON filename:

apherisfold workflow predict run \
  --model openfold3 --weight 3.0.0 \
  --input ./5sg6.json \
  --asset 5sg6=./5sg6.a3m

apherisfold workflow benchmark run \
  --model openfold3 --weight 3.0.0 --name eval \
  --input ./structures/ \
  --asset alpha=./alpha-chain-A.a3m \
  --asset alpha=./alpha-chain-B.a3m

Resolved MSA-to-chain mappings are recorded in the run's result.json; benchmark runs also print the mapping before submission.

Use --help on any subcommand for the full option reference and examples:

apherisfold workflow predict run --help
apherisfold workflow benchmark run --help
apherisfold workflow fine-tune prepare --help

License

This package is licensed under the Apheris Foundry Software License. The full license text is also included in every published wheel as LICENSE.

Support

Contact support@apheris.com for access and deployment assistance.