Fastfold Docs

SDK CLI

Script-friendly CLI examples for jobs, workflows, library uploads, and reports.

Use fastfold-cli for shell-friendly workflows with IDs by default and JSON output available via --json.

Tip: Use --help aggressively. The SDK CLI is organized into resource groups, so fastfold-cli --help, fastfold-cli jobs --help, or fastfold-cli workflows evolla --help are the fastest way to discover the exact flags for a task.

Discover commands

Use these help entry points first:

fastfold-cli --help
fastfold-cli fold --help
fastfold-cli jobs --help
fastfold-cli library --help
fastfold-cli workflows --help
fastfold-cli workflows openmm --help
fastfold-cli workflows openmmdl --help
fastfold-cli workflows evolla --help
fastfold-cli workflows boltzgen --help
fastfold-cli reports --help

Common cross-command flags:

  • --api-key overrides FASTFOLD_API_KEY
  • --base-url points the CLI at a different Fastfold deployment
  • --timeout controls HTTP timeout in seconds
  • --json prints the full API response instead of the default ID or simplified output

Payload and file input patterns used across the CLI:

  • --payload for inline JSON or YAML objects
  • --payload-file for JSON or YAML files
  • --file - or --payload-file - to read from stdin
  • --format auto|json|yaml when you need to force payload parsing

Command tree

Top-level commands:

fastfold-cli fold
fastfold-cli jobs ...
fastfold-cli library ...
fastfold-cli workflows ...
fastfold-cli reports ...

jobs subcommands:

fastfold-cli jobs create
fastfold-cli jobs from-yaml
fastfold-cli jobs results
fastfold-cli jobs wait
fastfold-cli jobs set-public
fastfold-cli jobs render-yaml
fastfold-cli jobs render-json

library subcommands:

fastfold-cli library create
fastfold-cli library get
fastfold-cli library upload

workflows subcommands:

fastfold-cli workflows create
fastfold-cli workflows get
fastfold-cli workflows status
fastfold-cli workflows task-results
fastfold-cli workflows execute
fastfold-cli workflows set-public
fastfold-cli workflows create-graph
fastfold-cli workflows get-yml
fastfold-cli workflows set-yml
fastfold-cli workflows create-from-yml
fastfold-cli workflows openmm ...
fastfold-cli workflows openmmdl ...
fastfold-cli workflows evolla ...
fastfold-cli workflows boltzgen ...

workflows evolla subcommands:

fastfold-cli workflows evolla from-fold-job
fastfold-cli workflows evolla from-file
fastfold-cli workflows evolla from-input

workflows openmm subcommands:

fastfold-cli workflows openmm from-fold-job
fastfold-cli workflows openmm from-manual-files
fastfold-cli workflows openmm from-workflow
fastfold-cli workflows openmm extract-frame

workflows openmmdl subcommands:

fastfold-cli workflows openmmdl prepare-script
fastfold-cli workflows openmmdl from-local-files
fastfold-cli workflows openmmdl from-workflow
fastfold-cli workflows openmmdl execute-draft
fastfold-cli workflows openmmdl extract-frame

workflows boltzgen subcommands:

fastfold-cli workflows boltzgen create-draft
fastfold-cli workflows boltzgen create-from-yml
fastfold-cli workflows boltzgen get-yml
fastfold-cli workflows boltzgen set-yml
fastfold-cli workflows boltzgen execute
fastfold-cli workflows boltzgen logs
fastfold-cli workflows boltzgen example-files
fastfold-cli workflows boltzgen build-spec

reports subcommands:

fastfold-cli reports slack

Fold jobs

fastfold-cli fold --sequence "LLGDFFRKSKEKIGKEFKRIVQRIKDFLRNLVPRTES" --model boltz-2
fastfold-cli jobs create --payload-file fastfold/examples/fold/job_payload.json
fastfold-cli jobs from-yaml --file fastfold/examples/fold/boltz2_affinity_input.yaml --model boltz-2
fastfold-cli jobs results <job_id> --json
fastfold-cli jobs wait <job_id> --json
fastfold-cli jobs set-public <job_id> --public
fastfold-cli jobs render-yaml --payload-file fastfold/examples/fold/job_payload.json
fastfold-cli jobs render-json --payload-file fastfold/examples/fold/boltz2_affinity_input.yaml --format yaml --json

Common fold and job flags:

  • fold --params accepts inline JSON or YAML for advanced model parameters
  • fold --constraints accepts inline JSON or YAML for constraints
  • jobs create --from-id and jobs from-yaml --from-id associate the job with a library item
  • jobs from-yaml --draft creates without dispatching immediately
  • jobs from-yaml --public sets public visibility at creation time
  • jobs wait --poll-interval, --wait-timeout, and --no-log control wait behavior

Workflows

fastfold-cli workflows create --payload-file fastfold/examples/openmm/from_manual_files.json
fastfold-cli workflows get <workflow_id> --json
fastfold-cli workflows status <workflow_id>
fastfold-cli workflows task-results <workflow_id> --json
fastfold-cli workflows execute <workflow_id>
fastfold-cli workflows set-public <workflow_id> --public
fastfold-cli workflows create-graph --workflow-name boltzgen_v1 --name demo
fastfold-cli workflows get-yml <workflow_id>
fastfold-cli workflows set-yml <workflow_id> --file ./workflow.yml --json
fastfold-cli workflows create-from-yml --workflow-name boltzgen_v1 --file ./workflow.yml --execute --json

Use the generic workflows commands when you already have a complete request body or when you need direct workflow.yml control.

OpenMM and OpenMMDL helpers

fastfold-cli workflows openmm from-fold-job <job_id> --sim-length-ns 0.2
fastfold-cli workflows openmm from-manual-files --pdb ./protein.pdb --pae ./pae.json --simulation-name AF-P00698 --sim-length-ns 10 --box-length 50
fastfold-cli workflows openmm from-workflow <workflow_id> --input-json '{"sim_length_ns": 5}'
fastfold-cli workflows openmm extract-frame <workflow_id> --time-ns 10 --json

fastfold-cli workflows openmmdl prepare-script --input-json fastfold/examples/openmmdl/from_local_files.json
fastfold-cli workflows openmmdl from-local-files --topology ./KEAP1kd.pdb --ligand ./IQK.sdf --simulation-name "KEAP1 + IQK" --input-json fastfold/examples/openmmdl/workflow_input.json
fastfold-cli workflows openmmdl from-local-files --topology ./KEAP1kd.pdb --ligand ./IQK.sdf --simulation-name "KEAP1 + IQK (Quick Water Box)" --input-json fastfold/examples/openmmdl/quick_water_box.workflow_input.json
fastfold-cli workflows openmmdl from-workflow <workflow_id> --prepare --json
fastfold-cli workflows openmmdl execute-draft <workflow_id> --json
fastfold-cli workflows openmmdl extract-frame <workflow_id> --time-ns 10 --json

Important helper flags:

  • workflows openmm from-workflow --input-json merges JSON or YAML into workflow_input
  • workflows openmmdl from-local-files --ligand is repeatable
  • workflows openmmdl from-local-files --run-analysis or --no-run-analysis toggles analysis
  • workflows openmmdl from-local-files --skip-prepare bypasses /prepare-script
  • workflows openmmdl from-local-files --draft-script creates in draft mode
  • both extract-frame commands accept --selection, --output-filename, and --dt-in-ps

Evolla helpers

fastfold-cli workflows evolla from-file ./model.cif --question "What is the function of this protein?" --json
fastfold-cli workflows evolla from-fold-job <job_id> --question "What is the function of this protein?" --json
fastfold-cli workflows evolla from-input --file fastfold/examples/evolla/from_fold_job.template.json --name "Evolla demo"
  • from-file uploads the structure via the Library API (file-type defaults to protein) and sets targetSource: upload
  • from-fold-job prefers the CIF URL from job results; if sourceUserId cannot be inferred, pass --source-user-id or set FASTFOLD_EVOLLA_SOURCE_USER_ID
  • from-input posts a workflow_input object as for Create Workflow Run with workflow_name: evolla_v1

BoltzGen helpers

fastfold-cli workflows boltzgen create-draft --name demo
fastfold-cli workflows boltzgen create-from-yml --file ./workflow.yml --name demo --execute --json
fastfold-cli workflows boltzgen get-yml <workflow_id>
fastfold-cli workflows boltzgen set-yml <workflow_id> --file ./workflow.yml --json
fastfold-cli workflows boltzgen execute <workflow_id> --json
fastfold-cli workflows boltzgen logs <workflow_id> --json
fastfold-cli workflows boltzgen example-files --json
fastfold-cli workflows boltzgen build-spec \
  --template-file fastfold/examples/boltzgen/minimal.workflow.yml \
  --replacements-file fastfold/examples/boltzgen/replacements.example.json \
  --output ./workflow.yml

Reminder: build-spec only generates the local workflow.yml. You still need to upload referenced inputs to the library and then submit or attach the resulting workflow YAML to a draft workflow.

Library and reports

fastfold-cli library create --name input-folder --type folder --json
fastfold-cli library get <item_id> --json
fastfold-cli library upload <item_id> ./protein.pdb ./ligand.sdf --json
fastfold-cli reports slack --markdown "## Demo Report"
fastfold-cli reports slack --markdown-file fastfold/examples/reports/sample_report.md

For library create, the main fields are --name, --type file|folder, --parent-id, --file-type, --origin, and --metadata.

For reports slack, pass either --markdown or --markdown-file. Use --report-name to label the saved report, and --no-save-to-library when you only want delivery without library persistence.

Last updated on

Install

Install, authenticate, configure, and start using the Fastfold Python SDK and CLI.

Fold

Structure prediction on Fastfold—models, artifacts, and SDK recipes from minimal submit to YAML and Boltz-2.

On this page

Discover commandsCommand treeFold jobsWorkflowsOpenMM and OpenMMDL helpersEvolla helpersBoltzGen helpersLibrary and reports