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).

nextmv help

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.

nextmv -h

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

nextmv version -h

account command

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

nextmv account [command]

Available account subcommands

account queue subcommand

nextmv help account queue

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.

Manage your SSO settings for your Nextmv account (premium only).

Usage:
  nextmv account sso [command]

Available Commands:
  configure   Configures a SSO integration on the enterprise admin account (Premium only).
  delete      Deletes SSO integration on the enterprise admin account (Premium only).
  disable     Disables SSO integration on the enterprise admin account (Premium only).
  enable      Enables SSO integration on the enterprise admin account (Premium only).
  get         Gets the SSO configuration.

Flags:
  -h, --help   Help for sso.

Global Flags:
  -c, --config string   Full path to config file.

Use "nextmv account sso [command] --help" for more information about a command.

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

Configures a SSO integration on the enterprise admin account (Premium only).
Only service initiated SSO is supported. One of either metadata url or metadata
file must be provided.

Usage:
  nextmv account sso configure [flags]

Examples:
  # Configures SSO on the account (with metadata url).
  $ nextmv account sso configure \
    --enabled \
    --metadata-url https://example.com/metadata.xml \
    --allow-non-domain-users
		

Flags:
      --allow-non-domain-users   Determines if non-domain users can be invited to accounts. Defaults to false.
  -e, --enabled                  Initial enabled state of SSO integration.Defaults to false.
  -h, --help                     Help for configure.
      --json                     The output to stdout is formatted as a JSON string.
      --metadata-file string     Path to the metadata file location for the SSO configuration.
      --metadata-url string      The metadata URL for the SSO configuration.

Global Flags:
  -c, --config string   Full path to config file.

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

Deletes SSO on an account. SSO must have been previously configured in the 
Nextmv console.

Usage:
  nextmv account sso delete [flags]

Examples:
  # deletes SSO on the account.
  nextmv account sso delete

Flags:
  -h, --help   Help for delete.

Global Flags:
  -c, --config string   Full path to config file.

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

Disables SSO on an account. SSO must have been previously configured in the 
Nextmv console.

Usage:
  nextmv account sso disable [flags]

Examples:
  # Disables SSO on the account.
  nextmv account sso disable

Flags:
  -h, --help   Help for disable.

Global Flags:
  -c, --config string   Full path to config file.

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

Enables SSO on an account. SSO must have been previously configured in the 
Nextmv console.

Usage:
  nextmv account sso enable [flags]

Examples:
  # Enables SSO on the account.
  nextmv account sso enable

Flags:
  -h, --help   Help for enable.

Global Flags:
  -c, --config string   Full path to config file.

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

Gets the SSO configuration for the account.

Usage:
  nextmv account sso get [flags]

Examples:
  # Gets the SSO configuration.
  nextmv account sso get

Flags:
  -h, --help   Help for get.

Global Flags:
  -c, --config string   Full path to config file.

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.

nextmv app [command]

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

nextmv app [command]

Available app subcommands

app cancel subcommand

nextmv app cancel [flags]

The cancel subcommand cancels a queued or running application run.

These are the available flags for the cancel subcommand:

app create subcommand

nextmv app create [flags]

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

nextmv app delete [flags]

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

app get subcommand

nextmv app get [flags]

The get subcommand gets the information related to an application.

app input subcommand

nextmv app input [flags]

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

nextmv app output [flags]

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

nextmv app list [flags]

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

app metadata subcommand

nextmv app metadata [flags]

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

nextmv app promote [flags]

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

nextmv app push [flags]

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

nextmv app result [flags]

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

nextmv app run [flags]

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.

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

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

nextmv app update [flags]

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.

nextmv app version [command]

Available commands for version subsuite

version create

nextmv app version create [flags]

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

nextmv app version delete [flags]

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

nextmv app version get [flags]

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

version list

nextmv app version list [flags]

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

version update

nextmv app version update [flags]

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.

nextmv app instance [command]

Available commands for instance subsuite

instance create

nextmv app instance create [flags]

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

instance delete

nextmv app instance delete [flags]

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

instance get

nextmv app instance get [flags]

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

instance list

nextmv app version list [flags]

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

instance update

nextmv app instance update [flags]

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

nextmv community [command]

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

These are the available subcommands for the community command:

clone subcommand

nextmv community clone [flags]

The clone subcommand clones a community app locally.

These are the available flags for the clone subcommand:

list subcommand

nextmv community list [flags]

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

nextmv 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:

nextmv help completion zsh

configure command

nextmv configure [flags]

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.

nextmv configure -a $API_KEY

experiment command

nextmv 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

nextmv experiment acceptance [command]

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

nextmv experiment acceptance delete [flags]

Delete an acceptance test.

acceptance init

nextmv experiment acceptance init [flags]

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

acceptance start

nextmv experiment acceptance start [flags]

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

nextmv experiment batch delete [flags]

Delete a batch experiment.

batch start

file is the payload sent to the API to start the experiment. More information on the

Start a batch experiment run.

batch result

nextmv experiment batch result [flags]

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

nextmv experiment input-set create [flags]

input-set list

nextmv experiment input-set list [flags]

input-set get

nextmv experiment input-set get [flags]

input-set update

nextmv experiment input-set update [flags]

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

shadow

nextmv experiment shadow [command]

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

nextmv experiment shadow create [flags]

shadow list

nextmv experiment shadow list [flags]

shadow result

nextmv experiment shadow result [flags]

shadow runs

nextmv experiment shadow runs [flags]

shadow start

nextmv experiment shadow start [flags]

shadow stop

nextmv experiment shadow stop [flags]

help command

nextmv help [command] [flags]

The help command displays the main help menu.

The Nextmv Command Line Interface (CLI) to interact with the Platform.

Usage:
  nextmv [command]

Available Commands:
  account       Manage your Nextmv account.
  app           Commands to manage and interact with your applications.
  community     Interact with community apps.
  completion    Generate the autocompletion script for the specified shell
  configure     Configure the Nextmv CLI.
  experiment    Commands to run and manage experiments.
  help          Help about any command
  marketplace   Commands to manage and interact with marketplace.
  release-notes View release notes for the Nextmv CLI.
  update        Updates the CLI tool.
  version       Prints the Nextmv CLI version.

Flags:
  -c, --config string   Full path to config file.
  -h, --help            Help for nextmv.

Use "nextmv [command] --help" for more information about a command.

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

marketplace command

nextmv marketplace [command]

The marketplace command set is used to manage marketplace commands.

These are the available Marketplace Subcommands

marketplace app subsuite

nextmv marketplace app [command]

Available marketplace app Subcommands

marketplace subscription subsuite

nextmv marketplace subscription [command]

Available marketplace subscription Subcommands

template command

Command "template" is deprecated, it will be removed in a future release. Contact us for more information: https://www.nextmv.io/contact.
DEPRECATED. This command will be deleted in a future release.
Contact us for more information: https://www.nextmv.io/contact.

Start modeling from a template in one of our supported languages.

Usage:

Flags:
  -h, --help   Help for template.

Global Flags:
  -c, --config string   Full path to config file.

The template command suite contains commands for interacting with templates.

These are the available subcommands for the template command:

init template subcommand

"--directory" flag, and list the available templates with the "list" command.

The init subcommand initializes a template locally.

These are the available flags for the init subcommand:

list template subcommand

Use the "--flat" flag to flatten the list of names/versions. Init a template with the "init" command.

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

nextmv update [version] [flags]

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

version command

nextmv version [flags]

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.