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

Quick start

# Log in with your Apheris Hub URL
apheris-foundry login --url https://hub.example.com

# See available workflow definitions
apheris-foundry workflows list

# Submit a run
apheris-foundry workflows run --workflow predict --input ./request.json

# Inspect the model IDs, weights, and default parameters advertised by Hub
apheris-foundry workflows models --workflow predict

# Override prediction parameters with a Hub-schema-validated JSON object
apheris-foundry workflows run --workflow predict --input ./request.json \
  --model-params '{"seeds":[7,9],"num_diffusion_samples":3}'

# Or provide the same JSON object from a file
apheris-foundry workflows run --workflow predict --input ./request.json \
  --model-params @./model-params.json

# Select a non-default model/weight advertised by the workflow
apheris-foundry workflows run --workflow predict --input ./request.json \
  --param model=<model-id> --weight <weight-version> \
  --model-params @./model-params.json

# List submitted runs
apheris-foundry jobs list

# Filter by workflow
apheris-foundry jobs list --workflow predict

# Inspect a run
apheris-foundry jobs get --id <job-id>

# Stream logs
apheris-foundry jobs logs --id <job-id>

# Download results
apheris-foundry jobs download --id <job-id>

# Print the error for a failed run
apheris-foundry jobs error --id <job-id>

# Delete a terminal (succeeded or failed) job and its stored data
apheris-foundry jobs delete --id <job-id>

# Skip the confirmation prompt
apheris-foundry jobs delete --id <job-id> --yes

Want to try prediction with a template? The template smoke example includes a sample CIF, a matching request, and commands to run a prediction and check the downloaded results.

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.