Getting Started With The Fovus CLI

The official CLI tool for interacting with the Fovus Serverless HPC Platform. Installation, setup, and usage documentation is provided here. Further detail is available via the CLI --help command or at our CLI documentation website.

Features include job creation (with validation), job status checking, and job file downloading. In addition, reusable job and user configurations with optional command-line overriding are supported. Additional features are detailed in this README and in our help documentation (linked above).

Installation

Prerequisites

Python and pip installation: https://www.python.org/downloads/
1. Click the "Download Python" button.
2. Select ALL of the following according to your operating system:
  1. Windows
    1. Install pip (should be selected by default).
    2. Add Python to PATH.
    3. Add Python to environment variables (this is generally found under "Customize Installation" and should be automatically enabled if you selected "Add Python to PATH").
  2. Unix-based OS
    1. Install or upgrade pip (under Customize)
    2. Shell profile updater (under Customize)
Close and reopen your Command Prompt/PowerShell (Windows) or terminal (Unix-based systems).
Install fovus using pip with the following command:

pip install fovus

Note:

The pip package is usually bundled with Python. If you have Python and you don't have pip, you can install pip at the following link: https://pip.pypa.io/en/stable/installation/.
Windows: If you encounter a command not found error and have already installed Python, try re-running the Python installer, selecting "Modify". In the following menus (you may have to click "Next"), select the following options:
1. Install pip (should be selected by default).
2. Add Python to environment variables.
Unix-based OS: If you encounter any Python-related issues, try reinstalling Python according to the instructions above.

Initial Setup

Before use, set up the following:

Make sure you have an account with https://app.fovus.co
Authenticate your account through the Fovus CLI

Authentication

To login with your Fovus credentials, run the command:

fovus auth login

To logout from the Fovus CLI, run the command:

fovus auth logout

To view the current user and workspace information or verify whether a user is authenticated, run the command:

fovus auth user

Windows - Python Can't Find Script

In "Run" (Windows + R), enter sysdm.cpl
System Properties will open up. Go to Advanced -> Environment Variables
Under "User variables for xxx", click the variable labeled "Path"
Click the "Edit" button under the "User variables for xxx" section
Click the "New" button in the "Edit environment variables" pane that opens
In the terminal you used to install the Fovus CLI, run the following command: pip show fovus (this will show a message similar to the sample output provided after these instructions)
Copy the "Location" value from the output of the above command (e.g., C:\Users\TestFovusUser\AppData\Local\Programs\Python\Python311\Lib\site-packages) and paste it as a new environment variable. Once it is pasted, replace the \Lib\site-packages with \Scripts (e.g., C:\Users\TestFovusUser\AppData\Local\Programs\Python\Python311\Scripts)
Click "OK" on all open environment variable windows.

Sample output for pip show fovus (reference from step 6 above):

PS C:\Users\TestFovusUser> pip show fovus
Name: fovus
Version: 1.0.6
Summary: The Fovus Python CLI
Home-page:
Author: Fovus Corporation
Author-email:
License:
Location: C:\Users\TestFovusUser\AppData\Local\Programs\Python\Python311\Lib\site-packages
Requires: boto3, dateparser, jsonschema, pycognito, requests, tqdm
Required-by:

Note: If the above fails, try reinstalling/modifying your Python and pip installation following the instructions under the "Prerequisites" section above.

Basic Usage

See the "Advanced Usage" section for additional options regarding file inclusion/exclusion for create job and download job files.

Viewing Your Config Files

fovus config open

Note:

Contains empty job and user config files for reference and copying.

Creating Jobs

This command will upload files from the specified directory to Fovus and create a job.

Upon job creation:

The following will be validated: your job configuration structure (if provided as JSON), your job configuration values against your chosen benchmarking profile, and your software configurations (if job is monolithic).
A .fovus folder will be created in your local file root directory, which will contain a job_data.json file (i.e., /path/to/job/file/root/directory/.fovus/job_data.json. This json is used to facilitate checking job status and downloading job files by tracking the job's jobID.

fovus job create "/path/to/job/config/file.json" "/path/to/job/file/root/directory"

Note:

To create your own job template, you have two options:
1. Create a job config through the Fovus web app:
  1. Login to the Fovus web app.
  2. Click "Create job" in the top right corner.
  3. Fill in all sections of the form. Uploading files is not necessary.
  4. Click the "Export" button in the top right corner. This will download a JSON file that you can use as a template.
2. Create a job config from an existing JSON template:
  1. Open the fovus config folder with fovus config open.
  2. Make a copy of either ~/.fovus/job_configs/FOVUS_job_template_containerized.json or ~/.fovus/job_configs FOVUS_job_template_monolithic.json.
  3. IMPORTANT: rename your copy, or it will be overwritten.
  4. Fill in the fields.
Each subdirectory in your job file root directory will be treated as its own task.
1. Folder and file names must only contain the following characters: a–z, A–Z, 0–9, hyphen (-), underscore (_), period (.), exclamation mark (!), and parentheses (()).
You can add the optional argument --job-name "your_job_name_here" to set a custom job name.

Getting Job Status

If you created the job using the Fovus CLI on the same local machine (i.e., the .fovus folder was created in your job root directory -- see "Creating job" section for details):

fovus job status --job-directory "/path/to/job/file/root/directory

If you did not create the job using the Fovus CLI:

fovus job status --job-id "your_job_id"

Note:

Job ID is viewable in the Web UI.

Downloading Completed Job Files

If you created the job using the Fovus CLI on the same local machine (i.e., the .fovus folder was created in your job root directory -- see "Creating job" section for details):

fovus job download "/path/to/job/file/root/directory"

If you did not create the job using the Fovus CLI:

fovus job download "/path/to/job/file/root/directory" --job-id "your_job_id"

Note:

Only new or updated files will be downloaded (checked using file hash).

Uploading Files to Fovus Storage

To upload files or directories to Fovus storage for archival, sharing, use in jobs, or access from workstations, utilize the following command:

fovus storage upload "/path/to/file/directory/or/file"

To upload a file to a specific path within the My Files section of Fovus storage, you can append the path within My Files to the command:

fovus storage upload "/path/to/file/directory/or/file" "your/destination/path"

Mounting Fovus Storage as a Network Drive

Supported operating systems: Windows, Ubuntu, CentOS, and Redhat.

To mount Fovus Storage as a network drive on your local machine, use the following command:

fovus storage mount

Supported file operations: sequential & random read, sequential write, overwrite, delete

Job files are read-only.

The Fovus Storage network file system does not support modifying existing files directly. To modify a file, overwrite it instead. We recommend using Fovus Storage as a cloud archive instead of a working directory due to suboptimal performance and usability.

Fovus Storage will be mounted as a network file system at /fovus-storage/ on Linux or <WindowsDrive>:\fovus-storage\ on Windows.

Prerequisites (Linux)

fovus storage mount needs two things that are not Python dependencies:

Package	Purpose
`mountpoint-s3` (the `mount-s3` binary)	Mounts Fovus Storage
FUSE (`libfuse2` / `fuse`, providing `fusermount`)	Lets `mount-s3` create the mount

(at is also used, optionally, to schedule the mount-credential refresh.)

If these are missing, fovus storage mount lists the packages it needs and asks before installing them. Installing FUSE, and mounting at the default system path /fovus-storage/, need sudo; the mount itself runs as your user. To pre-install the packages yourself:

# Ubuntu / Debian
sudo apt-get install -y fuse libfuse2 at
wget -qO /tmp/mount-s3.deb https://s3.amazonaws.com/mountpoint-s3-release/latest/x86_64/mount-s3.deb
sudo apt-get install -y /tmp/mount-s3.deb

# CentOS / RHEL
sudo yum install -y fuse fuse-libs at
sudo yum install -y https://s3.amazonaws.com/mountpoint-s3-release/latest/x86_64/mount-s3.rpm

Non-interactive / pipeline use

Run fovus -s storage mount to skip all prompts (the -s flag auto-confirms the package install).

By default, mounting also sets up automatic re-mounting on login and a background job that refreshes the mount credentials before they expire. On a host where you manage the mount lifecycle yourself, opt out:

fovus storage mount --no-auto-remount

fovus storage mount writes ~/.fovus/fovus-storage-mount.sh and fovus-storage-unmount.sh — plain shell scripts that (un)mount Fovus Storage directly, without the fovus CLI, network, or credentials. A pipeline can call these to re-mount or unmount while the mount credentials are still valid.

To unmount, run fovus storage unmount.

Advanced Usage

Include/Exclude File Patterns

When creating a job, the arguments --include-paths and --exclude-paths are available to you. These arguments are used to include/exclude filepaths for upload/download. Valid values for these arguments are alphanumeric along with the wildcards: * (matches any number of characters), ? (matches any single character).

For example:

--include-paths "Car*/*" "config?/*" includes:
- All files under any directory that begins with Car.
- All files in folders titled configX, where X is any character.
--exclude-paths "Car*/*.log" "local?/*" uploads all files except:
- All .log filetypes within every directory that begins with Car.
- All files in any directory titled localX where X is any character.

Usage With `fovus job create`

--include-paths will only upload filepaths (relative to the job root directory) that match the expressions provided.
--exclude-paths will upload all filepaths except those that match the expression provided.

Usage With `fovus job download`

--include-paths will only download filepaths (relative to the job root directory) that match the expressions provided.
--exclude-paths will download all filepaths except those that match the expression provided.

Overriding

Any value in a job config or a user config can be overriden by providing the respective json key as an argument. Examples are given below, and more details are available in --help.

Single-value Arguments

All single-value arguments (i.e., not lists) can be overriden using a single argument and a value. For example, the benchmarkingProfileName in your job config, you can do so by providing the argument --benchmarking-profile-name "your_benchmarking_profile_name_here".

Lists of Values

All lists of values can be overridden using a single argument and a list of values. For example, if you want to override the supportedCpuArchitectures in your job config, you can do so by providing the argument --supported-cpu-architectures "x86_64" "arm64".

Lists of Objects

Currently, the only list of objects that exists is the monolithicList, which is only used for monolithic jobs. The only value that can be overridden in a monolithicList is licenseCountPerTask. To do this, use the command --monolithic-override "vendor_name" "software_name" "license_feature" "your_new_license_count_here".

Note:

The monolithicList object must already exist in the job config JSON.
The vendor name, software name, and license feature are used to reference the specific object within the list and do not override existing values.
If an object that does not match the given vendor name, software name, and license feature does not exist, an error will be thrown.

Storage Connectors

A storage connector gives a job access to a storage location outside Fovus storage, such as a bucket your team already keeps data in. Connectors are set up for your cost center in your workspace settings; a job names the ones it needs, so it reads and writes that data in place instead of copying it into Fovus storage first.

A job can declare the storage connectors it may access using the optional storageConnectors key in the job config:

{
  "storageConnectors": ["shared-results", "vendor-data-2"]
}

The same list can be provided on the command line, which overrides the job config value:

fovus job create --storage-connectors "shared-results" --storage-connectors "vendor-data-2" JOB_CONFIG_FILE_PATH JOB_DIRECTORY

Note:

storageConnectors is optional. If the key is absent or null, it defaults to an empty list, and the job is submitted exactly as before.
The CLI checks only the shape of each name locally. A name may contain letters, digits, and hyphens (^[a-zA-Z0-9-]+$). Spaces, underscores, and slashes are rejected before the job is submitted so that typos are caught without a network round trip.
Whether a connector exists and whether you may use it is decided by Fovus at submission time, on every submission. The CLI does not resolve or cache connector names, because your access can change between a check and a submission. If the job is rejected, the message is shown unchanged: a connector that does not exist and one you may not use are different problems and need different fixes.

Access scope

Within a pipeline, connectors declared on any job are reachable from every job in that pipeline. A job in a pipeline may therefore be able to reach a connector it did not list itself. Outside a pipeline, a job is granted access to exactly the connectors it lists.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fovus-2.0.60-py3-none-any.whl (173.4 kB view details)

Uploaded Sep 1, 2026 Python 3

File details

Details for the file fovus-2.0.60-py3-none-any.whl.

File metadata

Download URL: fovus-2.0.60-py3-none-any.whl
Upload date: Sep 1, 2026
Size: 173.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for fovus-2.0.60-py3-none-any.whl
Algorithm	Hash digest
SHA256	`5cc23ecc2bb8d955648c78a3ea1ee74bcc1693c5f212117012d10a6875a775da`
MD5	`ae5045a4494d258082b95b7fc609a58e`
BLAKE2b-256	`a487e1997326295b3160ee8c464f6d9f68e4c5e3751905079662fd9ce344bd16`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fovus-2.0.60-py3-none-any.whl:

Publisher: python-release.yml on Fovus/fovus-cli-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fovus-2.0.60-py3-none-any.whl
- Subject digest: 5cc23ecc2bb8d955648c78a3ea1ee74bcc1693c5f212117012d10a6875a775da
- Sigstore transparency entry: 2669698613
- Sigstore integration time: Sep 1, 2026
Source repository:
- Permalink: Fovus/fovus-cli-python@8f5e7ae5f176d120e4d37fb83bf94924e7820d39
- Branch / Tag: refs/tags/2.0.60
- Owner: https://github.com/Fovus
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-release.yml@8f5e7ae5f176d120e4d37fb83bf94924e7820d39
- Trigger Event: release