Nextmv CLI

Nextmv CLI is a command line interface that you can use to interact with Nextmv. You can manage account information, make runs, create experiments and more. Available commands for Nextmv CLI are documented in this section.

When using Nextmv CLI you can display more information about any command with the help command or global help flag (-h).

Available commands

Available commands and their corresponding subcommands. You can navigate to each section to learn more about the specific command.

Global Flags

Global flags that can be added to any command.

-c, --config

This flag instructs the command to use the config file that is passed to it instead of the standard configuration file created with nextmv configure (though note that the existing configuration file is not modified in any way).

-h, --help

This flag displays the help menu.

You can also display the help for the specified command or subcommand. Here is an example using the version command:

account command

The nextmv account command set is used to manage your account.

Available account subcommands

account queue subcommand

The queue subcommand lists the queued or running application runs. A run is queued when the status_v2 in the metadata is queued.

nextmv account queue

account sso subcommand

The sso subsuite for the nextmv account command set is to configure SSO for an organization. For an overview on SSO and configuration see single sign-on.

Available commands for account sso subsuite

The nextmv account sso subsuite is used to manage sso configuration. This is a premium feature.

account sso configure subcommand

The sso configure subcommand configures SSO integration for your account with your identity provider.

These are the available flags for the sso configure subcommand:

Either --metadata-file or metadata-url must be specified, but not both.

account sso delete subcommand

The sso delete subcommand deletes the SSO integration for your account with your identity provider. Once deleted, your account will no longer require SSO login (or any other account within that SSO domain).

account sso disable subcommand

The sso disable subcommand disables the SSO integration for your account with your identity provider but leaves the configuration intact. All accounts within the SSO domain will no longer use SSO. This can be useful if you have an issue with your provider configuration.

account sso enable subcommand

The sso enable subcommand enables the SSO integration for your account with your identity provider. SSO must have been previously configured. All accounts within the SSO domain will use SSO.

account sso get subcommand

The sso get retrieves your current SSO configuration.

app command

The nextmv app command set is used to manage and run custom decision applications.

You can push new binaries to Nextmv Cloud and run them remotely with Nextmv CLI or using the Nextmv Cloud REST API.

To display more information about a command, use the help command or one of the help global flags: --help, -h.

Available app subcommands

app cancel subcommand

The cancel subcommand cancels a queued or running application run.

These are the available flags for the cancel subcommand:

app create subcommand

The create subcommand creates a new application. An application represents a problem you are solving and contains things like executable binaries, versions, and instances to manage and run your application. (See Apps core concepts for more)

These are the available flags for the create subcommand:

app delete subcommand

The delete subcommand deletes an application. When you delete an application all of the versions and instances are also deleted.

app get subcommand

The get subcommand gets the information related to an application.

app input subcommand

The input subcommand gets the input for a given application run and writes it to a file. By default, the filename will be autogenerated based on the run ID.

app output subcommand

The output subcommand gets the output for a given application run and writes it to a file. By default, the filename will be autogenerated based on the run ID.

app list subcommand

The list subcommand lists all of the applications for your account.

app metadata subcommand

The metadata subcommand gets the metadata results for the application run specified. Results contain the output of the run, and metadata related to the execution.

app promote subcommand

The promote subcommand creates a new version of an application from the last pushed binary, and assigns that version to the default instance. If you specify an instance ID, then the newly created version will be assigned to this instance and then this instance will be set as the app’s default instance (replacing the default instance if there was one prior). If the instance ID you specify does not exist, a new instance will be created using the specified ID (the name will be auto-generated), the newly created version assigned to the instance, and this newly created instance set as the app’s default instance.

Since the CLI is oriented towards the developer, remote runs made through the CLI that don't specify an instance will run the last pushed binary. (The default instance can be specified with the --default flag.)

Calls made to the Nextmv Cloud API endpoints that don’t specify an instance will run the binary specified in the default instance. (The last pushed binary can be specified in the API call with the reserved instance name devint which designates the latest binary.)

app push subcommand

The push subcommand updates the latest binary in the cloud with your local application build. You must run this from the directory containing your application project.

app result subcommand

The result subcommand gets the results for the application specified. Results contain the output of the run, and metadata related to the execution. If the run failed or is still in progress, then only metadata will be present in the results.

app run subcommand

The run subcommand starts a run of an application.

Some examples of using app run are given below.

Complete run workflow

Execute the complete run workflow (submit a run, poll for status, get the results). The output key will contain the actual output of the run. This is an aggregation of the other steps.

nextmv app run \
    --app-id $APP_ID \
    --instance $INSTANCE_ID \
    --input $INPUT_FILE \
    --options "solve.duration=10s,solve.iterations=20" \
    --wait

New run

Submit a new run. The run_id is returned.

nextmv app run \
    --app-id $APP_ID \
    --instance $INSTANCE_ID \
    --input $INPUT_FILE \
    --options "solve.duration=10s,solve.iterations=20"

Run metadata

Get a run metadata. The metadata.status key will contain the status of the run. Use the run_id obtained from submitting a run.

nextmv app metadata \
    --app-id $APP_ID \
    --run-id $RUN_ID

Run result

Get a run result. The output key will contain the actual output of the run, if the output format is JSON. Use the run_id obtained from submitting a run.

nextmv app result \
    --app-id $APP_ID \
    --run-id $RUN_ID

Run output

While the run result typically already contains the output, you can also get the output of a run directly. Use the run_id obtained from submitting a run. By default, the command writes the output to an automatically generated file. The output will be written out as recorded and without any formatting.

nextmv app output \
    --app-id $APP_ID \
    --run-id $RUN_ID

You can get the input of a run in the same way by using the nextmv app input command.

Get the logs of a run

You can get the logs of a run after it is finished. The logs contain everything that was printed to stderr during the run.

Running with log tailing

You can also tail logs while running, which will show you any output your application prints to stderr about every 30 seconds. If you use the --verbose flag then the results will also show when the run completes.

nextmv app run \
    --instance $INSTANCE_ID \
    --input $INPUT_FILE \
    --tail \
    --verbose

Cancel a run

To cancel a run, use the nextmv app cancel command.

nextmv app cancel \
   --app-id "<YOUR-APP-ID>" \
   --run-id "<YOUR-RUN-ID>"

app update subcommand

The update subcommand allows updating the mutable information on the specified application. The mutable information is limited to the name, description, and ID of the default instance. If the name, description, or default instance ID tag is undefined the corresponding value will not be updated.

app version subcommand

The version subsuite for the nextmv app command set is used to directly and explicitly manage application versions. The default workflow for the nexmtmv app command set handles most of the functionality of this subsuite implicitly.

Available commands for version subsuite

version create

The version create subcommand creates a new application version with the underlying binary defined by the current active development instance (i.e. the latest binary pushed to the app)

version delete

The version delete subcommand deletes a specified version from your application. Note that the version cannot be deleted if there are any instances running it.

version get

The version get subcommand gets the information related to an application version.

version list

The version list subcommand lists all of the versions for an application.

version update

The version update subcommand allows updating the mutable information on the specified version of your application. The mutable information is limited to the name and description of the version. If either the name or description tag are undefined, the corresponding value will not be updated.

app instance subcommand

The instance subsuite for the nextmv app command set is used to directly and explicitly manage application instances. The default workflow for the nexmtmv app command set handles limited functionality from this subsuite implicitly.

Available commands for instance subsuite

instance create

The instance create subcommand creates a new application instance with the underlying version specified by user input.

instance delete

The instance delete subcommand deletes a specified instance from your application.

instance get

The instance get subcommand gets the information related to an application instance.

instance list

The instance list subcommand lists all of the instances for an application.

instance update

The instance update subcommand allows updating the information on the specified instance of your application. The instance's name, description, and the ID of the underlying version it uses can be modified. If any of these values are not defined via flags, they will not be modified

community command

The community command suite contains commands for interacting with community apps.

These are the available subcommands for the community command:

clone subcommand

The clone subcommand clones a community app locally.

These are the available flags for the clone subcommand:

list subcommand

The list subcommand lists the available community apps. Use the corresponding flag to list an app’s versions instead.

These are the available flags for the list subcommand:

completion command

The completion command generates the autocompletion script for the Nextmv CLI for the specified shell.

Here is an example on displaying the completion for zsh:

configure command

The configure command adds or modifies your Nextmv API key for use with the Nextmv CLI. Running this command will create a config.yaml file (or modify it if already present) in the directory where your nextmv binary is located. Note that the base API endpoint will be set automatically with the default value when you pass your API key with the --api-key flag. This command is typically run once.

These are the available flags for the configure command:

Here is an example where the configure command is used to update the Nextmv API key with an environment variable.

experiment command

Experiments are used to test the performance of your models by running and comparing the results of various models, or a single model with multiple inputs.. From the CLI, you can create input sets and start new experiments. Experiments are run remotely on Nextmv Cloud and accessible via the Nextmv console.

Below is a list of available CLI subcommands

acceptance

Acceptance tests are used to obtain a go/no-go decision on deploying a new version of an application. The decision is based on the results of a list of user-defined metrics.

Below is a list of available CLI subcommands

acceptance delete

Delete an acceptance test.

acceptance init

Initialize the template for the metrics that an acceptance test uses.

acceptance start

Start an acceptance test.

batch

Batch experiments are used to run a set of inputs against a number of application instances on Nextmv Cloud. The results are aggregated and made available to the user in the Nextmv console.

batch delete

Delete a batch experiment.

batch start

Start a batch experiment run.

batch result

Get the result of a batch experiment run.

input-set

Input sets are used to define named inputs for a batch experiment that can be reused across experiments.

input-set create

input-set list

input-set get

input-set update

For more information use the --help flags for each command.

shadow

A shadow test is an experiment that runs in the background and compares the results of a baseline instance against a candidate instance. When the shadow test has started, any run made on the baseline instance will trigger a run on the candidate instance using the same input and options. For more information see the shadow tests reference.

shadow create

shadow list

shadow result

shadow runs

shadow start

shadow stop

help command

The help command displays the main help menu.

You can use help to display the help menu for any specified command or subcommand.

marketplace command

The marketplace command set is used to manage marketplace commands.

These are the available Marketplace Subcommands

marketplace app subsuite

Available marketplace app Subcommands

marketplace subscription subsuite

Available marketplace subscription Subcommands

template command

The template command suite contains commands for interacting with templates.

These are the available subcommands for the template command:

init template subcommand

The init subcommand initializes a template locally.

These are the available flags for the init subcommand:

list template subcommand

The list subcommand lists the available templates. Use the corresponding flag to list the template's versions instead.

These are the available flags for the list subcommand:

update command

The update command updates the Nextmv CLI. If the version is not specified, it will update to the latest one.

version command

The version command prints the Nextmv CLI version.

App options

Apps can typically be controlled via arguments. The structure and available options may vary depending on the app. For example, the Vehicle Routing solver nextroute accepts -model.objectives.cluster, which receives a float value and controls the importance of the clustering objective in comparison to the other objectives. Another common use case is to control the duration limit of the solver, which can be done via -solve.duration in the case of the unmodified nextroute solver (e.g.: -solve.duration 10s).

There are two cases where we want to pass options to the app:

1. When running the app locally.

   • In case of a Nextmv SDK based app, we can pass options to the app via the -- separator flag. For example:
   • Bash

   nextmv sdk run . -- -runner.input.path input.json -solve.duration 10s
   

   Copy
   • In case of a third-party app, like a Python OR-Tools based app, we can pass options just like the app expects them. For example:
   • Bash

   python main.py -input input.json -duration 10
   

   Copy

2. When running the app remotely on the platform.

   • In this case, we need to pass the options via the --options flag. Here, options are passed as a list of key=value strings separated by commas. For example:
   • Bash

   nextmv app run \
     --app-id routing-app \
     --input input.json \
     --options "solve.duration=10s,model.objectives.cluster=1.0"
   

   Copy
   • Note that we provide the input file separately via the --input flag. Nextmv CLI will upload the input file for us and the app will receive the input file via stdin on platform. Hence, the app needs to be able to read the input from stdin.