Skip to content

apheris🔗

Usage:

$ apheris [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • login: Interactive login to Apheris.
  • logout: Log out of Apheris.
  • version: Print the version of the Apheris CLI.
  • datasets: Use the sub-commands to interact with datasets.
  • compute: Use the sub-commands to interact with Compute Specs.
  • job: Use the sub-commands to interact with jobs.
  • jobspec: Use the sub-commands to interact with v2 jobs (JobSpecs).
  • models: Interact with the Apheris Registry.
  • artifacts: List artifacts and manage access to them.
  • orgs: List organizations.

apheris login🔗

Interactive login to Apheris. You will be forwarded to a website. For machine to machine applications (m2m), make sure the environment variables APH_SERVICE_USER_CLIENT_ID and APH_SERVICE_USER_CLIENT_SECRET are set. Call apheris login status to check your login status.

Usage:

$ apheris login [OPTIONS] [command]

Arguments:

  • command: Call apheris login status to show your login status.

Options:

  • --help: Show this message and exit.

apheris logout🔗

Log out of Apheris.

Usage:

$ apheris logout [OPTIONS]

Options:

  • --help: Show this message and exit.

apheris version🔗

Print the version of the Apheris CLI.

Usage:

$ apheris version [OPTIONS]

Options:

  • --help: Show this message and exit.

apheris datasets🔗

Use the sub-commands to interact with datasets.

Usage:

$ apheris datasets [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List all datasets that you have access to.
  • describe: Show information on a single dataset.
  • policy: Show the asset policy of a dataset that you have access to.

apheris datasets list🔗

List all datasets that you have access to.

Usage:

$ apheris datasets list [OPTIONS]

Options:

  • --help: Show this message and exit.

apheris datasets describe🔗

Show information on a single dataset.

Usage:

$ apheris datasets describe [OPTIONS] {dataset_id}

Arguments:

  • dataset_id: ID of the dataset to show information on. [required]

Options:

  • --help: Show this message and exit.

apheris datasets policy🔗

Show the asset policy of a dataset that you have access to.

Usage:

$ apheris datasets policy [OPTIONS] {dataset_id}

Arguments:

  • dataset_id: ID of the dataset to get the policy for. [required]

Options:

  • --help: Show this message and exit.

apheris compute🔗

Use the sub-commands to interact with Compute Specs.

Usage:

$ apheris compute [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • create: Create a Compute Spec on the Apheris orchestrator.
  • get: Get a Compute Spec from the Apheris orchestrator.
  • list: List all your Compute Specs.
  • activate: Activate a Compute Spec.
  • deactivate: Deactivate a Compute Spec - stops any running jobs and shuts down any infrastructure that was brought up for this Compute Spec.
  • activate-status: Get information on the status of the activation of a Compute Spec.
  • status: Get the status of a Compute Spec.
  • deactivate-all: Deactivate all Compute Specs that are in an active or transitional state.

apheris compute create🔗

Create a Compute Spec on the Apheris orchestrator. All parameters that are not passed as command line arguments will be interactively queried.

Usage:

$ apheris compute create [OPTIONS]

Options:

  • --dataset_ids <str>: Comma-separated dataset IDs, e.g. --dataset_ids=id1,id2,id3
  • --ignore_limits: The CLI sets some expected bounds for requested infrastructure resources. Use this flag to override the validation checks if your model requires more resources.
  • --client_n_cpu <float>: number of vCPUs of Compute Clients
  • --client_n_gpu <int>: number of GPUs of Compute Clients
  • --client_memory <int>: memory of Compute Clients [MByte]
  • --server_n_cpu <float>: number of vCPUs of Compute Aggregators
  • --server_n_gpu <int>: number of GPUs of Compute Aggregators
  • --server_memory <int>: memory of Compute Aggregators [MByte]
  • --model_id <str>: A model ID, e.g. apheris-statistics
  • --model_version <str>: The version of the model to use, e.g. v0.0.5
  • --num_clients_per_gateway <int>: Number of compute clients to spawn (optional, for advanced users)
  • --json <path>: File path to json file that describes a Compute Spec. Please use the interactive workflow once to learn about the expected format. If specified, all other arguments (except for force) must be None to avoid clashes.
  • -f, --force: Do not ask if user is certain, and do not ask for arguments interactively.
  • --help: Show this message and exit.

apheris compute get🔗

Get a Compute Spec from the Apheris orchestrator.

Usage:

$ apheris compute get [OPTIONS] [compute_spec_id]

Arguments:

  • compute_spec_id: The ID of the Compute Spec. If None, use the most recently used Compute Spec ID.

Options:

  • --help: Show this message and exit.

apheris compute list🔗

List all your Compute Specs.

Usage:

$ apheris compute list [OPTIONS]

Options:

  • -l, --limit <int>: Limit the number of Compute Specs shown. Set a negative number to show all [default: 10]
  • -v, --verbose: Show more detailed status information.
  • --active_only: List only active Compute Specs.
  • --help: Show this message and exit.

apheris compute activate🔗

Activate a Compute Spec. This will spin up a cluster of Compute Clients and Compute Aggregators.

Usage:

$ apheris compute activate [OPTIONS] [compute_spec_id]

Arguments:

  • compute_spec_id: The ID of the Compute Spec. If None, use the most recently used Compute Spec ID.

Options:

  • -f, --force: Do not ask if user is certain.
  • --help: Show this message and exit.

apheris compute deactivate🔗

Deactivate a Compute Spec - stops any running jobs and shuts down any infrastructure that was brought up for this Compute Spec. Use this if you have spun up a cluster of Compute Clients and Compute Aggregators, and don't need it anymore. Provided the Compute Spec remains approved, you can use activate to reinstate the infrastructure if needed at a later time.

Usage:

$ apheris compute deactivate [OPTIONS] [compute_spec_id]

Arguments:

  • compute_spec_id: The ID of the Compute Spec. If None, use the most recently used Compute Spec ID.

Options:

  • -f, --force: Do not ask if user is certain.
  • --help: Show this message and exit.

apheris compute activate-status🔗

Get information on the status of the activation of a Compute Spec.

Usage:

$ apheris compute activate-status [OPTIONS] [compute_spec_id]

Arguments:

  • compute_spec_id: The ID of the Compute Spec. If None, use the most recently used Compute Spec ID.

Options:

  • --help: Show this message and exit.

apheris compute status🔗

Get the status of a Compute Spec.

Usage:

$ apheris compute status [OPTIONS] [compute_spec_id]

Arguments:

  • compute_spec_id: The ID of the Compute Spec. If None, use the most recently used Compute Spec ID.

Options:

  • -v, --verbose: Show more information about Compute Spec status. Can be used to diagnose the issue when your Compute Spec is stuck in creating, for example, due to capacity constraints.
  • --help: Show this message and exit.

apheris compute deactivate-all🔗

Deactivate all Compute Specs that are in an active or transitional state.

Usage:

$ apheris compute deactivate-all [OPTIONS]

Options:

  • -f, --force: Do not ask for confirmation.
  • --help: Show this message and exit.

apheris job🔗

Use the sub-commands to interact with jobs.

Usage:

$ apheris job [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • run: Submit a job to run it.
  • schedule: Schedule a job with specified datasets, model, and resources.
  • list: List jobs.
  • status: Get the status and details of a job.
  • abort: Abort a currently running job.
  • abort-all: Abort all jobs matching the given criteria.
  • download-results: Download the results of a job.
  • logs: Download the logs for a job, which can be optionally written to a file.

apheris job run🔗

Submit a job to run it.

Usage:

$ apheris job run [OPTIONS]

Options:

  • --payload <str>: Arguments to provide to the job. You can either provide the filepath to a JSON file, or a string that contains a JSON compatible dictionary.
  • --compute-spec-id <uuid>: The ID of the Compute Spec.
  • -f, --force: Do not ask if user is certain.
  • -v, --verbose: Show more detailed information.
  • --help: Show this message and exit.

apheris job schedule🔗

Schedule a job with specified datasets, model, and resources.

Usage:

$ apheris job schedule [OPTIONS]

Options:

  • --dataset_ids <str>: Comma-separated dataset IDs, e.g. id1,id2,id3 [required]
  • --model_id <str>: A model ID, e.g. statistics [required]
  • --model_version <str>: The version of the model to use, e.g. 0.0.5 [required]
  • --payload <str>: Arguments to provide to the job. You can either provide the filepath to a JSON file, or a string that contains a JSON compatible dictionary
  • --timeout <float>: Timeout in seconds for waiting for compute spec to be running. Default is 10 minutes (600 seconds). This can happen for big models.
  • -f, --force: Do not ask if user is certain.
  • --client_n_cpu <float>: number of vCPUs of Compute Clients
  • --client_n_gpu <int>: number of GPUs of Compute Clients
  • --client_memory <int>: memory of Compute Clients [MByte]
  • --server_n_cpu <float>: number of vCPUs of Compute Aggregators
  • --server_n_gpu <int>: number of GPUs of Compute Aggregators
  • --server_memory <int>: memory of Compute Aggregators [MByte]
  • --num_clients_per_gateway <int>: Number of compute clients to spawn (optional)
  • --new_cs: Create a new compute spec regardless of prior matching compute specs.
  • --queue-id, --queue_id <str>: Queue ID for sequential execution. Same ID = jobs run one at a time. Uses the v2 endpoint.
  • --no-auto-cleanup, --no_auto_cleanup: Skip compute spec deactivation after job completion. Uses the v2 endpoint.
  • --help: Show this message and exit.

apheris job list🔗

List jobs.

Usage:

$ apheris job list [OPTIONS]

Options:

  • --compute-spec-id <uuid>: The ID of the Compute Spec. If None, returns all jobs
  • --use-v2, --use_v2: Use the v2 jobs endpoint. Deprecated: use apheris jobspec instead.
  • -v, --verbose: Show queue_id, duration, and timing breakdown columns (--use-v2 only).
  • --help: Show this message and exit.

apheris job status🔗

Get the status and details of a job.

Usage:

$ apheris job status [OPTIONS]

Options:

  • --job-id <str>: The ID of the job. If None, use the most recently used job ID.
  • -v, --verbose: Show more detailed information.
  • --use-v2, --use_v2: Use the v2 jobs endpoint. Deprecated: use apheris jobspec instead.
  • --help: Show this message and exit.

apheris job abort🔗

Abort a currently running job.

Usage:

$ apheris job abort [OPTIONS]

Options:

  • --job-id <str>: The ID of the job. If None, use the most recently used job ID.
  • -f, --force: Do not ask if user is certain.
  • --use-v2, --use_v2: Use the v2 jobs endpoint. Deprecated: use apheris jobspec instead.
  • --help: Show this message and exit.

apheris job abort-all🔗

Abort all jobs matching the given criteria.

Usage:

$ apheris job abort-all [OPTIONS]

Options:

  • --only-statuses <str>: Comma-separated list of statuses to target. V1 allowed values: any non-terminal status (anything not starting with 'finished.'). V2 allowed values: CREATED, PROVISIONING, RUNNING. Defaults to all abortable statuses for the selected API version.
  • --only-created-by-me: Only abort jobs created by the currently logged-in user. V2 only.
  • --only-queue-id <str>: Only abort jobs belonging to this queue ID. V2 only.
  • --use-v2, --use_v2: Use the v2 jobs endpoint. Deprecated: use apheris jobspec instead.
  • -f, --force: Skip the confirmation prompt.
  • --help: Show this message and exit.

apheris job download-results🔗

Download the results of a job.

Usage:

$ apheris job download-results [OPTIONS] [download_path]

Arguments:

  • download_path: Directory to store the downloaded results

Options:

  • --job-id <str>: The ID of the job. If None, use the most recently used job ID.
  • --use-v2, --use_v2: Use the v2 jobs endpoint. Deprecated: use apheris jobspec instead.
  • --help: Show this message and exit.

apheris job logs🔗

Download the logs for a job, which can be optionally written to a file.

Usage:

$ apheris job logs [OPTIONS]

Options:

  • --storage-path <file>: File in which to store logs (plaintext, or JSON with --orchestrator)
  • --job-id <str>: The ID of the job (V1 UUID or V2 'job-*' ID). If None, use the most recently used job ID.
  • --orchestrator: Fetch logs from orchestrator service instead of job service
  • --help: Show this message and exit.

apheris jobspec🔗

Use the sub-commands to interact with v2 jobs (JobSpecs). A JobSpec bundles the compute-spec request and job payload into a single submission and drives the full lifecycle (activate, submit, execute, deactivate) server-side, so you do not manage the compute spec separately as with the job commands.

Usage:

$ apheris jobspec [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • create: Create a JobSpec from a raw spec and payload.
  • list: List JobSpecs.
  • status: Get the status and details of a JobSpec.
  • logs: Show the logs for a JobSpec.
  • compute-statuses: Show the per-gateway compute status events for a JobSpec.
  • artifacts: List the data artifacts a JobSpec produced that you own.
  • abort: Abort a running JobSpec.
  • abort-all: Abort all JobSpecs matching the given criteria.
  • download: Download and extract the output of a JobSpec.
  • cleanup: Release idle compute resources left by --no-auto-cleanup jobs.

apheris jobspec create🔗

Create a JobSpec from a raw spec and payload.

Usage:

$ apheris jobspec create [OPTIONS]

Options:

  • --spec <str>: Compute-spec request, as a path to a JSON file or an inline JSON string. Keys: datasets (list of dataset IDs), model ({"id", "version"}), and optionally resources and numClientsPerGateway. [required]
  • --payload <str>: Job arguments, as a path to a JSON file or an inline JSON string. The payload is model-dependent; see the individual model's documentation for its expected fields. [required]
  • --queue-id <str>: Queue ID for sequential execution. Jobs sharing a queue ID run one at a time and reuse a warm compute spec, avoiding repeated activation.
  • --no-auto-cleanup: Keep the compute spec active after the job finishes. Results live on the spec and are deleted when it is deactivated, so you must use this flag to download them afterwards. The spec stays active until you release it with apheris jobspec cleanup, so remember to clean it up.
  • --idempotency-key <str>: Replay-safe create; a matching key returns the existing JobSpec.
  • --description <str>: Free-text description stored on the JobSpec.
  • --wait: Wait until the job reaches a terminal status before returning.
  • --timeout <float>: Max seconds to wait when --wait is set. [default: 600.0]
  • --poll-interval <float>: Seconds between polls when --wait is set. [default: 5.0]
  • -f, --force: Do not ask for confirmation.
  • --help: Show this message and exit.

apheris jobspec list🔗

List JobSpecs.

Usage:

$ apheris jobspec list [OPTIONS]

Options:

  • --all: Show jobs belonging to others in your org, not just your own (availability depends on your role). This can return a large number of results.
  • -v, --verbose: Show queue_id, duration, and timing breakdown columns.
  • --only-queue-id <str>: Only show jobs in this queue ID.
  • --help: Show this message and exit.

apheris jobspec status🔗

Get the status and details of a JobSpec.

Usage:

$ apheris jobspec status [OPTIONS]

Options:

  • --job-id <str>: The job ID (same identifier as elsewhere in the CLI; a JobSpec is created per job). If omitted, the most recently used job ID is used.
  • -v, --verbose: Show timing and execution steps.
  • --help: Show this message and exit.

apheris jobspec logs🔗

Show the logs for a JobSpec.

Usage:

$ apheris jobspec logs [OPTIONS]

Options:

  • --job-id <str>: The job ID (same identifier as elsewhere in the CLI; a JobSpec is created per job). If omitted, the most recently used job ID is used.
  • --storage-path <file>: File to write the logs to. If omitted, print to stdout.
  • --format <text|json>: Output format: 'text' (columns) or 'json' (NDJSON). [default: text]
  • --help: Show this message and exit.

apheris jobspec compute-statuses🔗

Show the per-gateway compute status events for a JobSpec.

Usage:

$ apheris jobspec compute-statuses [OPTIONS]

Options:

  • --job-id <str>: The job ID (same identifier as elsewhere in the CLI; a JobSpec is created per job). If omitted, the most recently used job ID is used.
  • --help: Show this message and exit.

apheris jobspec artifacts🔗

List the data artifacts a JobSpec produced that you own. Download one with apheris artifacts download --artifact-id &lt;id&gt;.

Usage:

$ apheris jobspec artifacts [OPTIONS]

Options:

  • --job-id <str>: The job ID. If omitted, the most recently used job ID is used.
  • --help: Show this message and exit.

apheris jobspec abort🔗

Abort a running JobSpec. This aborts the job; the compute spec is then deactivated automatically unless the job was created with --no-auto-cleanup, in which case it stays active until cleaned up.

Usage:

$ apheris jobspec abort [OPTIONS]

Options:

  • --job-id <str>: The job ID (same identifier as elsewhere in the CLI; a JobSpec is created per job). If omitted, the most recently used job ID is used.
  • -f, --force: Do not ask for confirmation.
  • --help: Show this message and exit.

apheris jobspec abort-all🔗

Abort all JobSpecs matching the given criteria.

Usage:

$ apheris jobspec abort-all [OPTIONS]

Options:

  • --only-statuses <str>: Comma-separated statuses to target. Allowed values: CREATED, PROVISIONING, RUNNING. Defaults to all abortable statuses.
  • --only-queue-id <str>: Only abort jobs in this queue ID.
  • --all: Abort jobs belonging to others in your org, not just your own (availability depends on your role). By default only your own jobs are considered.
  • -f, --force: Skip the confirmation prompt.
  • --help: Show this message and exit.

apheris jobspec download🔗

Download and extract the output of a JobSpec.

Usage:

$ apheris jobspec download [OPTIONS] [download_path]

Arguments:

  • download_path: Directory to store the downloaded results.

Options:

  • --job-id <str>: The job ID (same identifier as elsewhere in the CLI; a JobSpec is created per job). If omitted, the most recently used job ID is used.
  • -f, --force: Overwrite the target directory without asking if it is not empty.
  • --help: Show this message and exit.

apheris jobspec cleanup🔗

Release idle compute resources left by --no-auto-cleanup jobs.

Finds compute specs that are still active but that no job is using and no queued job is waiting to reuse, then deactivates them to free resources. This does not stop or change any job. Download any results you need first; they are deleted when the spec is released.

Usage:

$ apheris jobspec cleanup [OPTIONS]

Options:

  • --all: Also release idle specs belonging to others in your org, not just your own. Availability depends on your role.
  • -f, --force: Skip the confirmation prompt.
  • --help: Show this message and exit.

apheris models🔗

Interact with the Apheris Registry.

Usage:

$ apheris models [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List models that are available in the Apheris Registry.
  • get: Get a model by its ID.
  • list-versions: Get a list of all versions available for a given model.
  • add-version: Add a new version to an existing model in the Apheris Registry.

apheris models list🔗

List models that are available in the Apheris Registry. Note that only the 3 most recent versions of each model are shown.

Usage:

$ apheris models list [OPTIONS]

Options:

  • --help: Show this message and exit.

apheris models get🔗

Get a model by its ID.

Usage:

$ apheris models get [OPTIONS] {model_id}

Arguments:

  • model_id: Apheris ID of a model. Can be obtained via Apheris UI or CLI. [required]

Options:

  • -v, --verbose: Show more detailed status information.
  • --help: Show this message and exit.

apheris models list-versions🔗

Get a list of all versions available for a given model.

Usage:

$ apheris models list-versions [OPTIONS] {model_id}

Arguments:

  • model_id: Apheris ID of a model. Can be obtained via Apheris UI or CLI. [required]

Options:

  • --help: Show this message and exit.

apheris models add-version🔗

Add a new version to an existing model in the Apheris Registry.

Usage:

$ apheris models add-version [OPTIONS] {model_id}

Arguments:

  • model_id: Apheris ID of the model to which you want to add a version to. Obtainable via Apheris UI or CLI. [required]

Options:

  • --version <str>: Version number for the new model version. Needs to match the repo that holds the built image. [required]
  • --digest <str>: Digest for the new model. Needs to match the repository that holds the built image. [required]
  • --commit-hash <str>: Hash for the new model version. [required]
  • --engine-version <str>: Engine version, for example nvflare:2.6.0. For information on supported engines and versions, please contact your Apheris representative. [required]
  • --help: Show this message and exit.

apheris artifacts🔗

List artifacts and manage access to them.

Usage:

$ apheris artifacts [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List artifacts your organization can share, or, when --artifact-id is provided, list access grants for that artifact.
  • grant: Grant access to an artifact.
  • revoke: Revoke access to an artifact.
  • upload: Create an external artifact, upload files, and mark them complete.
  • download: Download an artifact

apheris artifacts list🔗

List artifacts your organization can share, or, when --artifact-id is provided, list access grants for that artifact.

Usage:

$ apheris artifacts list [OPTIONS]

Options:

  • -i, --artifact-id, --id <str>: Artifact ID to list access grants for (shorthand: -i / --id). If omitted, list shareable artifacts for your organization.
  • -s, --page-size <int range>: Number of artifacts to return when listing shareable artifacts. [default: 20; x>=1]
  • -t, --type <str>: Artifact type filter when listing shareable artifacts (checkpoint, metric, log, result).
  • --help: Show this message and exit.

apheris artifacts grant🔗

Grant access to an artifact.

Usage:

$ apheris artifacts grant [OPTIONS]

Options:

  • -i, --artifact-id, --id <str>: ID of the artifact to grant access to (shorthand: -i / --id). [required]
  • -e, --email <str>: Email that should get access to this artifact (shorthand: -e).
  • -o, --org-id <str>: Organization ID that should get access to this artifact (shorthand: -o). Use a value from apheris orgs list.
  • --help: Show this message and exit.

apheris artifacts revoke🔗

Revoke access to an artifact.

Usage:

$ apheris artifacts revoke [OPTIONS]

Options:

  • -i, --artifact-id, --id <str>: ID of the artifact (shorthand: -i / --id). [required]
  • -a, --access-id <str>: ID of the access grant to revoke (shorthand: -a). [required]
  • --help: Show this message and exit.

apheris artifacts upload🔗

Create an external artifact, upload files, and mark them complete.

Usage:

$ apheris artifacts upload [OPTIONS]

Options:

  • -n, --name <str>: Name of the artifact to create or reuse within your organization. [required]
  • -t, --type <str>: Artifact type: checkpoint, metric, log, or result. [required]
  • -f, --file <file>: Local file to upload. Repeat this option to upload multiple files to the same artifact.
  • -k, --key <str>: File key/name inside the artifact for a single-file upload. Defaults to the local file name. Nested paths are not supported.
  • -m, --metadata <str>: Optional metadata as a JSON object.
  • --model-id <str>: Optional model ID associated with the artifact.
  • --model-version <str>: Optional model version associated with the artifact.
  • --help: Show this message and exit.

apheris artifacts download🔗

Download an artifact

Usage:

$ apheris artifacts download [OPTIONS]

Options:

  • -i, --artifact-id, --id <str>: ID of the artifact (shorthand: -i / --id). [required]
  • -p, --download-path <path>: Directory to store the downloaded files. If not provided, files will be downloaded to the current working directory.
  • --help: Show this message and exit.

apheris orgs🔗

List organizations.

Usage:

$ apheris orgs [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List organizations.

apheris orgs list🔗

List organizations.

Usage:

$ apheris orgs list [OPTIONS]

Options:

  • --help: Show this message and exit.