Command-Line Interface¶

epic¶

A CLI for interacting with the EPIC API.

epic [OPTIONS] COMMAND [ARGS]...

admin¶

Administrative commands.

epic admin [OPTIONS] COMMAND [ARGS]...

update-setting¶

Update a system setting.

SETTING: The name of the setting to update (e.g., instance_types) VALUE: The new value for the setting. For lists, use comma-separated values.

Example: epic admin update-setting instance_types “m5.xlarge,m5.2xlarge”

epic admin update-setting [OPTIONS] SETTING VALUE [PROJECT_NAME]

Arguments

SETTING¶: Required argument

VALUE¶: Required argument

PROJECT_NAME¶: Optional argument

billing¶

Reports on the project’s monthly spend to date.

If no subcommand is provided, it displays the current monthly spend from the EPIC API.

Args:

project_name_option (str, optional): The name of the project. Defaults to the: active project.

epic billing [OPTIONS] COMMAND [ARGS]...

Options

--project <project_name_option>¶: The name of the project. Defaults to the active project.

report¶

Generates a PDF spend report.

epic billing report [OPTIONS] [PROJECT_NAME]

Options

--year <year>¶: Year for the report (YYYY)

--month <month>¶: Month for the report (1-12)

Arguments

PROJECT_NAME¶: Optional argument

catalog¶

Commands for interacting with the EPIC catalog.

The catalog provides information about available applications and compute resources (instance types) that can be used to run jobs.

epic catalog [OPTIONS] COMMAND [ARGS]...

list-applications¶

Lists available applications in the catalog.

This command retrieves and displays a list of all HPC applications that can be run through the EPIC platform. The output includes the application’s display name, a brief description, and the unique app_code used when submitting jobs.

param project_name:: The name of the project to use. Defaults to the active project.

epic catalog list-applications [OPTIONS] [PROJECT_NAME]

Arguments

PROJECT_NAME¶: Optional argument

list-instances¶

Lists available compute instance types in the catalog.

This command retrieves and displays a list of the AWS EC2 instance types that are available for running jobs in the current deployment. The output includes the instance type name, the number of vCPUs, and the available memory in GB.

The list of available instances is configurable by the system administrator and is validated against the instances available in the AWS region where the EPIC API is deployed.

param project_name:: The name of the project to use. Defaults to the active project.

epic catalog list-instances [OPTIONS] [PROJECT_NAME]

Arguments

PROJECT_NAME¶: Optional argument

config¶

Commands for managing project configurations.

epic config [OPTIONS] COMMAND [ARGS]...

add¶

Adds or updates a project configuration from a user-specific JSON file.

This command reads a JSON file typically generated for a new user, which contains all the necessary API endpoints and identifiers for a project. It saves this information into the main CLI config file (~/.epic/config) under the project’s name.

Args:: user_json_file (str): The path to the user’s JSON configuration file.

epic config add [OPTIONS] USER_JSON_FILE

Arguments

USER_JSON_FILE¶: Required argument

list¶

Lists all configured projects.

Reads the main config file and prints the names of all projects that have been configured.

epic config list [OPTIONS]

init¶

Initializes a session for a configured project.

This command authenticates the user with AWS Cognito using the stored username and password for the specified project. Upon successful authentication, it prints shell commands to set environment variables containing the API token and active project name.

To apply these variables to your current session, you should wrap this command in eval (for bash/zsh) or pipe it to Invoke-Expression (for PowerShell).

Example (bash/zsh):: eval “$(epic init epic-project)”
Example (PowerShell):: epic init epic-project | Invoke-Expression
Args:: project_name (str): The name of the project to initialize.

epic init [OPTIONS] PROJECT_NAME

Arguments

PROJECT_NAME¶: Required argument

job¶

Commands for managing jobs.

epic job [OPTIONS] COMMAND [ARGS]...

cancel¶

Cancels a specific job.

Args:: job_id (int): The unique identifier for the job to be cancelled. project_name (str, optional): The name of the project. Defaults to the active project.

epic job cancel [OPTIONS] JOB_ID [PROJECT_NAME]

Arguments

JOB_ID¶: Required argument

PROJECT_NAME¶: Optional argument

create¶

Creates a new job from a JSON file.

Args:

job_json_file (str): The file path to the JSON file containing the job: definition.
project_name (str, optional): The name of the project. Defaults to the: active project.

Example job.json files:

The job.json file can have the following optional fields:

instance_types: A list of instance types to use for the job. If not specified, the default instance types are used.
Use the epic catalog list-instances command to see the available instance types.

{
    "name": "Test Job Array",
    "jobs": [{
        "name": "Test OpenFOAM Job",
        "spec": {
            "app_code": "my-openfoamv8",
            "tasks": [{"reference": "main-task",
                        "partitions": 64,
                        "runtime": 1,
                        "task_distribution": "core",
                        "memory_gb": 16,
                        "instance_types": ["m5.xlarge"]
                    }]
        },
        "input_data": {"path": "HPC_motorbike/Small/v8"},
        "app_options": {"base_command": ". /opt/openfoam8/etc/bashrc && ./Allrun"},
        "cluster": {"queue_code": "batch-single-node"}
    }]
}

{
    "name": "Test Job Array",
    "jobs": [{
        "name": "Test OpenFOAM Job",
        "spec": {
            "app_code": "my-openfoam2212",
            "tasks": [{"reference": "main-task",
                        "partitions": 32,
                        "runtime": 1,
                        "task_distribution": "core",
                        "memory_gb": 16,
                        "instance_types": ["m5.xlarge"]
                    }]
        },
        "input_data": {"path": "v2212/motorBike"},
        "app_options": {"base_command": "su sudofoam -c '. /usr/lib/openfoam/openfoam2212/etc/bashrc && ls -lta && ./Allclean && ./Allrun'"},
        "cluster": {"queue_code": "batch-single-node"}
    }]
}

epic job create [OPTIONS] JOB_JSON_FILE [PROJECT_NAME]

Arguments

JOB_JSON_FILE¶: Required argument

PROJECT_NAME¶: Optional argument

get¶

Gets detailed information about a specific job.

Args:: job_id (int): The unique identifier for the job. project_name (str, optional): The name of the project. Defaults to the active project.

epic job get [OPTIONS] JOB_ID [PROJECT_NAME]

Arguments

JOB_ID¶: Required argument

PROJECT_NAME¶: Optional argument

list¶

Lists all current jobs and their status.

Args:

project_name (str, optional): The name of the project. Defaults to the: active project.

epic job list [OPTIONS] [PROJECT_NAME]

Arguments

PROJECT_NAME¶: Optional argument

tail¶

Tails the logs of a specific job.

Args:: job_id (int): The unique identifier for the job. project_name (str, optional): The name of the project. Defaults to the active project.

epic job tail [OPTIONS] JOB_ID [PROJECT_NAME]

Arguments

JOB_ID¶: Required argument

PROJECT_NAME¶: Optional argument

keys¶

Gets temporary data session keys as environment variables.

This command fetches temporary AWS credentials and prints them as export commands, allowing for direct S3 access.

Args:

project_name (str, optional): The name of the project. Defaults to the: active project.

epic keys [OPTIONS] [PROJECT_NAME]

Options

--awsconfig¶: Output in AWS config file format.

Arguments

PROJECT_NAME¶: Optional argument

project¶

Commands for managing projects.

epic project [OPTIONS] COMMAND [ARGS]...

get¶

Gets details for a project, including its monthly spend limit.

Args:

project_name (str, optional): The name of the project. Defaults to the: active project.

epic project get [OPTIONS] [PROJECT_NAME]

Arguments

PROJECT_NAME¶: Optional argument

update-spend¶

Sets the monthly spend limit for a project (admin only).

Args:: limit (int): The new monthly spend limit. project_name (str, optional): The name of the project. Defaults to the active project.

epic project update-spend [OPTIONS] LIMIT [PROJECT_NAME]

Arguments

LIMIT¶: Required argument

PROJECT_NAME¶: Optional argument

user¶

User management commands (admin only).

epic user [OPTIONS] COMMAND [ARGS]...

create¶

Creates a new user and generates a config file for them (admin only).

This command calls the user creation endpoint of the API. Upon successful creation, it generates a new JSON configuration file named {username}_config.json containing the necessary details for the new user to configure their own CLI.

Args:: username (str): The username for the new user. email (str): The email address for the new user. password (str): The password for the new user. project (str, optional): The name of the project to use for the admin user. Defaults to the active project.

epic user create [OPTIONS] USERNAME EMAIL PASSWORD

Options

--project <project>¶: The project configuration to use for the admin user. Defaults to the active project.

Arguments

USERNAME¶: Required argument

EMAIL¶: Required argument

PASSWORD¶: Required argument

delete¶

Deletes a user (admin only).

Args:: username (str): The username of the user to delete. project (str, optional): The name of the project to use. Defaults to the active project.

epic user delete [OPTIONS] USERNAME

Options

--project <project>¶: The project configuration to use. Defaults to the active project.

Arguments

USERNAME¶: Required argument

Command-Line Interface¶

epic¶

admin¶

update-setting¶

billing¶

report¶

catalog¶

list-applications¶

list-instances¶

config¶

add¶

list¶

init¶

job¶

cancel¶

create¶

get¶

list¶

tail¶

keys¶

project¶

get¶

update-spend¶

user¶

create¶

delete¶

epiccli

Navigation

Related Topics