The Fovus Python CLI
Project description
Installation
Prerequisites
- Python and pip installation: https://www.python.org/downloads/
- Click the "Download Python" button.
- If you have an option of installing pip, select that option. (This should be the default.)
- Install fovus using pip with the following command:
pip install fovus
Note: pip 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/.
Initial setup
Before use, set up the following:
- User config
- Password environment variable
User config
A user config is for a pre-existing user that is already set up in the Fovus web UI.
The following values can be viewed on the Fovus web UI by clicking on your profile icon in the top right of the page:
username
: the email address used for your account.workspaceId
: the ID for the workspace you would like to use. The workspace ID can be found by clicking on the user icon in the web UI.
Set up your CLI user config with the following command:
fovus --configure
Note:
- This user config will save to
~/.fovus/user_configs/FOVUS_default_user_config.json
. - To view all your configs, use
fovus --open-config-folder
. - The user config can also be provided in the following ways (these will override default user config):
- Using the following parameters:
--username your_username
and--workspace-id your_workspace_id
. - Using the following parameter:
--user-config-file-path /path/to/your/user_config.json
- Using the following parameters:
Password environment variable
Export your Fovus password as an environment variable by following the instructions for your system:
Unix-based systems
export FOVUS_CLI_PASSWORD="your_password_here"
Windows
- Run
setx FOVUS_CLI_PASSWORD "your_password_here"
in command prompt - Close your command prompt and open a new one (to refresh the environment variables)
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 --open-config-folder
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, 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 --create-job --job-config-file-path "/path/to/job/config/file.json" --job-file-root-directory "/path/to/job/file/root/directory"
Note:
- To create your own job template, do the following:
- Open the fovus config folder with
--open-config-folder
. - Make a copy of either
~/.fovus/job_configs/FOVUS_job_template_containerized.json
or~/.fovus/job_configs FOVUS_job_template_monolithic.json
. - IMPORTANT: rename your copy, or it will be overwritten.
- Fill in the fields.
- Open the fovus config folder with
- Each subdirectory in your job file root directory will be treated as its own task.
- 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 --get-job-current-status --job-file-root-directory "/path/to/job/file/root/directory
If you did not create the job using the Fovus CLI:
fovus --get-job-current-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 --download-job-files --job-file-root-directory "/path/to/job/file/root/directory"
If you did not create the job using the Fovus CLI:
fovus --download-job-files --job-file-root-directory "/path/to/job/file/root/directory" --job-id "your_job_id"
Note:
- Only new or updated files will be downloaded.
Advanced usage
Include/Exclude file patterns
When creating a job, the arguments --include-input
and --exclude-input
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-input "Car*/*" "config?/*"
includes:- All files under any directory that begins with
Car
. - All files in folders titled
configX
, whereX
is any character.
- All files under any directory that begins with
--exclude-input "Car*/*.log" "local?/*"
uploads all files except:- All
.log
filetypes within every directory that begins withCar
. - All files in any directory titled
localX
whereX
is any character.
- All
- The same logic applies for
--include-output
and--exclude-output
except those are used for downloading job files.
Usage with create job (--create-job)
--include-input
will only upload filepaths (relative to the job root directory) that match the expressions provided.--exclude-input
will upload all filepaths except those that match the expression provided.
Usage with download job files (--download-job-files)
--include-output
will only download filepaths (relative to the job root directory) that match the expressions provided.--exclude-output
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 --benchmarkingProfileName "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 --supportedCpuArchitectures "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.
Troubleshooting
Windows - Python can't find script
Windows
- Run
echo %USERPROFILE%\AppData\Roaming\Python\PythonXX\Scripts
, replacingPythonXX
with your version (can find usingpython--version
). For example, if my python version is 3.11.2, I will replacePythonXX
withPython311
- Run
setx PATH "%PATH%;C:\path\to\scripts"
, replacingC:\path\to\scripts
with the modified output from step 1. - Close and reopen your command prompt.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.