Apheris Foundry CLI

Command-line interface for submitting and managing Foundry workflow runs 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 apheris-foundry python=3.11 -y
conda activate apheris-foundry
pip install apheris-foundry-cli

Windows (Anaconda Prompt or PowerShell)

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

Activate the environment at the start of each session with conda activate apheris-foundry.

venv (standard Python)

Linux / macOS (venv)

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

Windows (PowerShell, venv)

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

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

Verify

apheris-foundry --version
apheris-foundry --help

Upgrade

pip install --upgrade apheris-foundry-cli

Login

Connect to your Hub using the URL provided by your team:

apheris-foundry login --url https://hub.example.com

Follow the sign-in instructions. The CLI saves your session for later commands. Use apheris-foundry logout to sign out, or log in again to switch Hubs.

Install agent skills

If you use an AI agent, install the CLI guidance for your agent:

apheris-foundry skills install --agent codex
# Or: apheris-foundry skills install --agent claude

The CLI skill is bundled and can be installed offline. After login, install workflow guidance directly from your Hub:

apheris-foundry workflows list
apheris-foundry skills install --workflow predict --agent codex

Use --path ./.agents/skills instead of --agent for another agent or a project directory. Reload skills in your agent if needed. Installing skills copies instructions; it does not log in or submit a job.

skills list shows bundled CLI skills and every workflow skill from your active Hub together. If Hub is unavailable, bundled skills still appear; unavailable workflow skills are quietly skipped. Display the selected skill without installing it:

apheris-foundry skills show apheris-foundry-hub
apheris-foundry skills show --workflow predict
apheris-foundry skills show apheris-workflow-predict
# Install every bundled and Hub workflow skill after login:
apheris-foundry skills install --all --agent codex

The default skills install --agent codex installs all bundled skills offline. Use --force when you want to replace an installed skill, including after changing Hubs or upgrading workflows. Replacement removes local edits and stale files in that skill only.

Older Hubs or custom workflows may not provide skills yet. In that case, the CLI reports the API error; ask your Hub administrator to deploy workflow skills. See Using the CLI for help and skill provenance details.

Quick start: predict a structure

After login, check that your Hub offers prediction:

apheris-foundry workflows get --workflow predict
apheris-foundry workflows docs --workflow predict
apheris-foundry workflows models --workflow predict

Save this small example as request.json:

{
  "queries": [{
    "chains": [{
      "chain_id": "A",
      "polymer_type": "protein",
      "sequence": "GSAEYVRALFDFNGNDEEDLPFKKGDILRIRDKPEEQWWNAEDSEGKRGMIPVPYVEKYHHHHHH"
    }]
  }]
}

Submit it using your Hub's default model settings:

apheris-foundry workflows run --workflow predict --input request.json

Folders and ZIP files use binary archive upload on Hub versions that support POST /api/v1/foundry/runs/upload:

apheris-foundry workflows run --workflow aqcell-finetune --input ./input/ --name training
apheris-foundry workflows run --workflow aqcell-finetune --input ./finetune-input.zip --strip-archive-root --name training

Folders are packaged automatically as an uncompressed ZIP in a temporary directory, then streamed to Hub. The temporary archive is removed after submission, including on failure. Existing ZIPs are validated; pass a ZIP alone. Hidden files and directories (dot-prefixed path components) are excluded. ZIPs containing them are streamed into a filtered temporary ZIP; other ZIPs are uploaded unchanged. Binary contents and relative paths are preserved by default. For the supplier's extra input/ folder, pass --strip-archive-root explicitly. Folder uploads need local temporary disk space roughly equal to the dataset size. Uploads and expanded archives are limited to 1 GiB; the server controls the entry count; links, traversal and conflicting paths are rejected. A failed network upload must be submitted again; uploads are not resumable or reusable datasets. Single text-file inputs retain the existing JSON submission path for older Hub versions.

This uploads the input and starts a job on Hub. Copy the returned job ID and use it in the commands below:

apheris-foundry jobs get --id <job-id>
apheris-foundry jobs logs --id <job-id>
# After the job succeeds:
apheris-foundry jobs download --id <job-id> --output ./results

If the job fails, use apheris-foundry jobs error --id <job-id> to inspect the error before retrying. Prediction requires a Hub with the model and compute resources configured; this example uses those resources.

Override model parameters inline or from a JSON file. Select models and weights advertised by workflows models:

apheris-foundry workflows run --workflow predict --input request.json \
  --model-params '{"seeds":[7,9],"num_diffusion_samples":3}'
apheris-foundry workflows run --workflow predict --input request.json \
  --param model=<model-id> --weight <weight-version> \
  --model-params @./model-params.json

For optional templates, see the template prediction example. For other workflows and model overrides, see Using the CLI.

Command reference

Authentication

Workflow definitions (workflows)

Run instances (runs)

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

apheris-foundry workflows run --help
apheris-foundry jobs get --help

--name optionally names the run. Omitted or blank names submit an unnamed run.

--model-params accepts one JSON object. Use an inline object for short overrides, or prefix a JSON filename with @ to load the object from that file. Before submitting the run, the CLI retrieves the selected model version, weight, and capability schema from Hub and validates the object. Use workflows models to discover available model IDs and weights.

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.

Model weights (weights)

weights list lists deployed weights visible to the caller. Filter with --run-id, --model, --version or --task; model and version together also include vendor weights. --include-deleted includes historical records whose files are gone. --json preserves the API response.

apheris-foundry weights list --model aqcell --version aqcell:0.2.0 --json
apheris-foundry weights deploy --run-id <job-id> --path <run-relative-bundle-directory> --json
apheris-foundry workflows models --workflow aqcell --json
apheris-foundry workflows run --workflow aqcell --input ./input --weight <weight-id>

weights deploy registers a job artifact through Hub; it does not upload local weights. Use the path shown by jobs get, including the complete directory for AQCell bundles. Optional --task, --description, --derived-from and repeated --capability values accompany the request; Hub derives and validates model identity and ownership. --dry-run true weights deploy ... prints the request without submission. Retain the producing job and verify selection in the target workflow's model catalog before reuse.

Workflow skill responses may include shared presentation skills. Installation validates their content digests and installs them alongside the workflow skill; --all deduplicates equal versions and rejects conflicting ones. The shared source lives in foundry-cli and travels through Hub, not in this Python package.

The optional skill resources field currently carries only vocabulary.json. The CLI checks its name, UTF-8 byte limit, SHA-256 and JSON syntax before writing it beside the workflow SKILL.md. A malformed resource prevents installation. Older Hubs omit resources; updated AQCell skills state that preflight vocabulary is then unavailable rather than claiming membership was checked.

Public compound resolution (no Hub required)

apheris-foundry tools compounds resolve --name gemcitabine --json
apheris-foundry tools compounds resolve --cid 60750 --json
apheris-foundry tools compounds resolve --cid 60750 --offline --json

Resolves exact PubChem records with isomeric SMILES, InChIKey, source and timestamp. Only public names/CIDs should be sent; supplied proprietary structures need no public lookup. Ambiguous matches stop for clarification. No automatic parent/salt substitution. Responses are cached locally for 30 days; offline use marks stale entries. Use --refresh for fresh evidence or --cache-dir to isolate a project cache. The shared chemical-identity and foundry-scientific-integrity skills also work without Hub through documented official APIs.

jobs download preserves the workflow's result.json; the CLI's download manifest is cli-result.json. A conflicting artifact with that name is rejected rather than overwritten. --result-view controls that CLI manifest's detail.