Using the CLI

The Nuvolos Python API allows you to list objects and create workloads directly in the CLI.

Display help

Show available commands:

nuvolos --help

Slugs and identifiers

Nuvolos objects (organisations, Spaces, Instances, Applications) are identified by slugs in the CLI — normalised representations of their names. Slugs are unique within their level:

• Organisation slugs are globally unique.

• Space slugs are unique within an organisation.

• Instance slugs are unique within a Space.

• Application slugs are unique within an Instance.

All nuvolos ... list commands accept the --format flag to format the output in json or yaml:

List organisations

nuvolos orgs list

Lists the organisations you are affiliated with.

List Spaces

nuvolos spaces list

Lists Spaces in the current organisation. On a local machine or to query a different organisation, use --org <org_slug>:

nuvolos spaces list --org <org_slug>

List running Nuvolos applications

To list the applications you have started and are currently running in Nuvolos, use the nuvolos apps running command.

This command will also display the status of apps (STARTING, RUNNING, STOPPING) and the current CPU and memory usage of apps.

You can filter the list of running applications for a given org/space/instance or application by specifying additional flags to the command:

List Nuvolos applications

To list the Nuvolos applications in the current Nuvolos instance you are working on, run the nuvolos apps list command.

If you are using the CLI on your computer or you want to list the applications in another Nuvolos organization/space/instance, you need to specify the slugs of the organization/space/instance in the command: nuvolos apps list --org <org_slug> --space <space_slug> --instance <instance_slug>

Start an application

First, get the slug of the application you wish to run with the nuvolos apps list command, then start the application with the nuvolos apps start <app_slug> command.

If you want the command to wait until the application has started, you should specify the --wait flag:

This behavior is particularly useful when running a "Start app" -> "Execute command" -> "Stop app" pipeline, as you can be sure that the application will be ready to execute commands when the nuvolos app start <app_slug> --wait command returns.

Starting an application with a different size

You can start a Nuvolos application from the API in a different size, without needing to reconfigure it. First, you need to identify the node_pool slug for the credit-based resource size you want to use.

You can get the list of available credit based-sizes, also termed node pools with command:

nuvolos apps nodepools

Then start with the chosen node pool:

nuvolos apps start <app_slug> --node-pool="<slug>" --wait

Running apps on credit-based resource sizes consumes Credits. Please check if your Nuvolos space is configured to run credit-based workloads.

Executing a command in an application

You can run a command in a running Nuvolos application as if you had a bash terminal opened in the given application. This lets you create an automated workflow to execute a workload on Nuvolos. You do this by automatically starting a pre-configured application, running a program in the application, and then stopping the application when the command finishes.

To submit a command for execution, use:

nuvolos apps execute --app <app_slug> 'YOUR COMMAND'

Currently, not all Nuvolos application types support running commands. JupyterLab, VSCode (except for the versions with Airflow), Spyder, Terminal and newer RSudio apps support command execution only.

To list these applications, select the api_command_run:enabled tag on the Add new application screen.

Output and logs of executed commands

Upon every command execution, a new folder is created in the selected application's instance under the /files/nuvolos_api_out folder in a <timestamp>_<request_id> format, where the request ID (reqid) is returned by the CLI command. A metadata.json file is created to store details such as the application context, submission timestamp, and the submitted command.

By default, the standard output and the standard error of your command are redirected to separate files to ensure preservation. The files are located in the folder introduced above, called output.log and error.log, respectively.

nuvolos apps execute supports default an output redirect when exactly one command is submitted. If you submitted a command sequence (e.g. python prepare.py && python evaluate.py), you need to specify the files where you intend to redirect the stdout and stderr of each command. Otherwise, the results of the commands without specifications will be saved in the default location.

Stop an application

You can stop a running Nuvolos application with the command:

nuvolos apps stop --app <app_slug>: