Reference

Nextmv CLI

Technical reference for the Nextmv Command Line Interface (CLI).

Nextmv CLI is a command line interface that you can use to interact with Nextmv.

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

Usage:
  nextmv [command]
Copy

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

nextmv help
Copy

Available commands

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

CommandDescriptionSubcommands
accountManage your Nextmv account.queue
appManage and interact with applications you create.create, delete, get, list, list-versions, promote, push, result, run, metadata, cancel
communityInteract with community apps.clone, list
completionGenerate auto-completion script for a specified shell.bash, fish, powershell, zsh
configureSetup Nextmv CLI.
experimentThis command set is used to manage and run experiments.acceptance, batch, input-set, shadow
helpDisplay help.
marketplaceCommands to manage and interact with marketplace.
templateInteract with community templates.init, list
updateUpdate Nextmv CLI.
versionPrint the version of Nextmv CLI.

Global Flags

Global flags that can be added to any command.

FlagDescription
-c, --config stringFull path to config file.
-h, --helpGet help for 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:

nextmv version -h
Copy

account command

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

nextmv account [command]
Copy

Available account subcommands

CommandDescriptionFlags
queueList the queue of runs that are pending to be executed or running.

account queue subcommand

nextmv help account queue
Copy

The queue subcommand lists the queued or running application runs.

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]
Copy

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

nextmv app [command]
Copy

Available app subcommands

CommandDescriptionFlags
cancelCancels a running or queued application run--app-id, --run-id
createCreates a new application in your account--app-id, --description, --name
deleteDeletes an application--app-id, --confirm
getGets an application configured in your account--app-id
inputGets an application run's input--app-id, --run-id, --output
instanceA subsuite of commands to manage the instances for your application
listLists the applications configured for your account
metadataGets the result metadata of an application run--app-id, --output, --run-id
promotePromotes an application version--app-id, --description, --name
pushPushes the current project to a cloud application--app-id
resultGets the results of an application run--app-id, --output, --run-id
runRuns an application instance configured in your account--app-id, --default, --input, --instance, --options, --timeout, --wait
updateUpdates an application--app-id, --description, --instance-id, --name
versionA subsuite of commands to manage the versions for your application

app cancel subcommand

nextmv app cancel [flags]
Copy

The cancel subcommand cancels a queued or running application run.

These are the available flags for the cancel subcommand:

FlagDescription
-a, --app-id stringRequired The id of the application.
-r, --run-id stringRequired The id of the run.

app create subcommand

nextmv app create [flags]
Copy

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:

FlagDescription
-a, --app-id stringRequired The id of the app. Must be unique within your account and can contain lower case letters, numbers, and dashes. The maximum length is 30 characters.
-n, --name stringRequired The name for the application.
-d, --description stringOptional The description for the application.

app delete subcommand

nextmv app delete [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The id of the application to delete.

app get subcommand

nextmv app get [flags]
Copy

The get subcommand gets the information related to an application.

FlagDescription
-a, --app-id stringRequired The id of the application to get.

app input subcommand

nextmv app input [flags]
Copy

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.

FlagDescription
-a, --app-id stringRequired The id of the application.
-r, --run-id stringRequired The id of the run.
-o, --output stringOptional The file to write to. Use '-' to write to stdout.

app output subcommand

nextmv app output [flags]
Copy

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.

FlagDescription
-a, --app-id stringRequired The id of the application.
-r, --run-id stringRequired The id of the run.
-o, --output stringOptional The file to write to. Use '-' to write to stdout.

app list subcommand

nextmv app list [flags]
Copy

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

app metadata subcommand

nextmv app metadata [flags]
Copy

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.

FlagDescription
-a, --app-id stringRequired The id of the application for the run.
-r, --run-id stringRequired The id of the run.
-o, --output stringOptional The output location to use. Stdout used if not specified.

app promote subcommand

nextmv app promote [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The id of the application to promote.
-n, --name stringOptional The name to assign to the version. Set to the app name + a unique ID if not specified.
-d, --description stringOptional The description for the version.
-v, --version-id stringOptional The ID to assign to the version. Set to app ID + a unique ID if not specified.
-i, --instance-id stringOptional The ID to assign to the default instance. Set to the app ID if not specified.

app push subcommand

nextmv app push [flags]
Copy

You must be inside your project when running this command.

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.

FlagDescription
-a, --app-id stringRequired The id of the application to push to.

app result subcommand

nextmv app result [flags]
Copy

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.

FlagDescription
-a, --app-id stringRequired The id of the application for the run.
-r, --run-id stringRequired The id of the run.
-o, --output stringOptional The output file to write. Stdout used if not specified.

app run subcommand

nextmv app run [flags]
Copy

The run subcommand starts a run of an application.

FlagDescription
-a, --app-id stringRequired The id of the application to run.
-i, --input stringOptional The input file to use (Stdin if not specified).
-d, --input stringOptional Run the default instance. Runs the last pushed application binary if not specified.
-w, --wait stringOptional Waits for the run to complete, and outputs results to stdout.
-t, --timeout stringOptional The maximum time in seconds to poll for results (default 60 seconds).
--instance stringOptional The id of the instance to use.
-o, --options stringArrayOptional The options used in an app run. Format: --options "solve.duration=10s,other.key=value".

app update subcommand

nextmv app update [flags]
Copy

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.

FlagDescription
-a, --app-id stringRequired The ID of the application to update.
-d, --description stringOptional The application description. Will remain unchanged if not specified.
-i, --instance-id stringOptional The default instance ID. Will remain unchanged if not specified.
-n, --name stringOptional The application name. Will remain unchanged if not specified.

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]
Copy

Available commands for version subsuite

CommandDescriptionFlags
version createCreates a new version for your application--app-id --version-id --name --description
version deleteDeletes the specified application version.--app-id --version-id --confirm
version getGets the specified application version.--app-id --version-id
version listLists the versions for your application--app-id
version updateUpdates information about an application version.--app-id --version-id --name --description

version create

nextmv app version create [flags]
Copy

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)

FlagDescription
-a, --app-id stringRequired The ID of the application to create a version for.
-d, --description stringOptional The version description.
-n, --name stringOptional The version name. Will be set to app name + unique id if not specified.
-v, --version-id stringOptional The ID of the version to create. Must be unique within the application. Version ID will be generated automatically if this flag is unset.

version delete

nextmv app version delete [flags]
Copy

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.

FlagDescription
-a, --app-id stringRequired The application ID for the application to delete a version from.
-v, --version-id stringRequired The ID of the version to delete.
--confirm booleanOptional Set to skip prompt to delete.

version get

nextmv app version get [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The application ID for the application to get a version from.
-v, --version-id stringRequired The ID of the version to get.

version list

nextmv app version list [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The id of the application to list versions for.

version update

nextmv app version update [flags]
Copy

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.

FlagDescription
-a, --app-id stringRequired The ID of the application to update the version of.
-v, --version-id stringRequired The ID of the version to update.
-d, --description stringOptional The version description. Will remain unchanged if not specified.
-n, --name stringOptional The version name. Will remain unchanged if not specified.

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]
Copy

Available commands for instance subsuite

CommandDescriptionFlags
instance createCreates a new instance for your application--app-id --instance-id --version-id --name --description --options
instance deleteDeletes the specified application instance.--app-id --instance-id --confirm
instance getGets the specified application instance.--app-id --instance-id
instance listLists the instances for your application--app-id
instance updateUpdates information about an application instance.--app-id --instance-id --version-id --name --description --options

instance create

nextmv app instance create [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The ID of the application to create an instance for.
v, --version-id stringRequired The ID of the underlying version to be used by the instance.
-d, --description stringOptional The instance description.
-n, --name stringOptional The instance name. Will be set to app name + unique id if not specified.
-i, --instance-id stringOptional The ID of the instance to create. Must be unique within the application. Instance ID will be generated automatically if this flag is unset.
-o, --options stringArrayOptional The options passed to the instance. Format: --options "solve.duration=10s,other.key=value".

instance delete

nextmv app instance delete [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The application ID for the application to delete an instance from.
-i, --instance-id stringRequired The ID of the instance to delete.
--confirm booleanOptional Set to skip prompt to delete.

instance get

nextmv app instance get [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The application ID for the application to get an instance from.
-i, --instance-id stringRequired The ID of the instance to get.

instance list

nextmv app version list [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The id of the application to list instances for.

instance update

nextmv app instance update [flags]
Copy

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

FlagDescription
-a, --app-id stringRequired The ID of the application to update the instance of.
-i, --instance-id stringRequired The ID of the instance to update.
-v, --version-id stringOptional The ID of the underlying version the instance uses. Will remain unchanged if not specified.
-d, --description stringOptional The instance description. Will remain unchanged if not specified.
-n, --name stringOptional The instance name. Will remain unchanged if not specified.
-o, --options stringArrayOptional The options passed to the instance. Format: --options "solve.duration=10s,other.key=value".

community command

nextmv community [command]
Copy

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

These are the available subcommands for the community command:

SubcommandDescription
cloneClone a community app locally. Learn more here.
listList the community apps and/or their versions. Learn more here

clone subcommand

nextmv community clone [flags]
Copy

The clone subcommand clones a community app locally.

These are the available flags for the clone subcommand:

FlagDescription
-a, --app stringThe name of the app you want to clone locally.
-d, --directory stringThe directory in which to initialize the app.
-v, --version stringThe version of the app you want to clone. If not provided, the "latest" version will be used.

list subcommand

nextmv community list [flags]
Copy

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:

FlagDescription
-a, --app stringList the versions of the given app.
-f, --flat booleanFlat list of apps’s names. Flat list of an app’s versions when using the "app" flag.

completion command

nextmv completion [command]
Copy

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
Copy

configure command

nextmv configure [flags]
Copy

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:

FlagDescription
-a, --api-key stringNextmv API key.
-s, --showPrints the current configuration.

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
Copy

experiment command

To try out experiments with Nextmv, you must have a Nextmv account and be signed up for a free trial or paid account. For questions, please contact Nextmv support.

nextmv experiment [command]
Copy

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

CommandDescription
acceptanceA subsuite of commands to manage acceptance tests
batchA subsuite of commands to start batch experiments
input-setA subsuite of commands to manage input sets
shadowCommands to manage shadow tests

acceptance

nextmv experiment acceptance [command]
Copy

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

CommandDescriptionFlags
deleteDeletes an acceptance test.--app-id, --experiment-id, --confirm
initInitializes metrics template for an acceptance test.--metrics
startStarts an acceptance test.--app-id, --baseline-instance-id, --candidate-instance-id, --confirm, --definition, --description, --experiment-id, --input-set-id, --metrics, --name, --option-sets

acceptance delete

nextmv experiment acceptance delete [flags]
Copy

Delete an acceptance test.

FlagDescription
-a, --app-id stringThe identifier for the app that the acceptance test ran on.
--confirmSet to skip prompt to confirm.
-e, --experiment-id stringThe identifier for the experiment - acceptance test.

acceptance init

nextmv experiment acceptance init [flags]
Copy

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

FlagDescription
-m, --metrics stringThe location to write the metrics file to. (default "metrics.json").

acceptance start

nextmv experiment acceptance start [flags]
Copy

Start an acceptance test.

FlagDescription
-a, --app-id stringThe identifier for the app to use for the experiment.
--baseline-instance-id stringThe instance ID to use as the baseline for the experiment.
--candidate-instance-id stringThe instance ID to use as the candidate for the experiment.
--confirmSet to skip prompt to confirm.
--definition stringThe path to a definition file to use to start the experiment.
-d, --description stringThe experiment description.
-e, --experiment-id stringThe identifier for the experiment.
-s, --input-set-id stringThe input set ID to use. If not specified, a new input set will be created.
-m, --metrics stringThe location of the metrics configuration file.
-n, --name stringThe experiment name.
-o, --option-sets stringThe option sets for the experiment. Formatted as JSON, e.g '{"option1":{"diagram.expansion.limit":"1"},"option2":{"limits.duration":"100ms"}}'

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.

CommandDescriptionFlags
deleteDelete a batch experiment.--app-id, --experiment-id, --confirm
startStart a batch experiment run.--app-id, --experiment-id, --description, --name, --input-set-id, --instance-ids, --option-sets, --definition
resultGets the result of a batch experiment run.--app-id, --experiment-id, --output

batch delete

nextmv experiment batch delete [flags]
Copy

Delete a batch experiment.

FlagDescription
-a, --app-id stringThe identifier for the app that the experiment ran on.
--confirmSet to skip prompt to confirm.
-e, --experiment-id stringThe identifier for the experiment.

batch start

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

Start a batch experiment run.

batch result

nextmv experiment batch result [flags]
Copy

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.

CommandDescriptionFlags
createCreate an input set from historic runs--app-id, --name, --description, --input-set-id, --instance-id, --start-time, --end-time, --run-ids --limit
listList input sets--app-id
getShow an input set--app-id, --input-set-id
updateUpdate an input set--app-id, --input-set-id, --name, --description

input-set create

nextmv experiment input-set create [flags]
Copy

input-set list

nextmv experiment input-set list [flags]
Copy

input-set get

nextmv experiment input-set get [flags]
Copy

input-set update

nextmv experiment input-set update [flags]
Copy

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

shadow

nextmv experiment shadow [command]
Copy

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.

Command DescriptionFlags
createCreates a new shadow test.
  • -a, --app-id (string)
  • -x, --baseline-instance-id (string)
  • -y, --candidate-instance-id (string)
  • -d, --description (string)
  • -e, --end-time (string)
  • -h, --help
  • -m, --maximum-runs (int)
  • -n, --name (string)
  • -i, --shadow-test-id (string)
  • -s, --start-time (string)
listGets a list of all shadow tests.
  • -a, --app-id (string)
  • -h, --help
resultGets the result of a shadow test.
  • -a, --app-id (string)
  • -h, --help
  • -i, --shadow-test-id (string)
runsGets the runs of a shadow test.
  • -a, --app-id (string)
  • -h, --help
  • -i, --shadow-test-id (string)
startStarts a shadow test.
  • -a, --app-id (string)
  • -h, --help
  • -i, --shadow-test-id (string)
stopStops a shadow test.
  • -a, --app-id (string)
  • -h, --help
  • -r, --intent (string)
  • -i, --shadow-test-id (string)

shadow create

nextmv experiment shadow create [flags]
Copy

shadow list

nextmv experiment shadow list [flags]
Copy

shadow result

nextmv experiment shadow result [flags]
Copy

shadow runs

nextmv experiment shadow runs [flags]
Copy

shadow start

nextmv experiment shadow start [flags]
Copy

shadow stop

nextmv experiment shadow stop [flags]
Copy

help command

nextmv help [command] [flags]
Copy

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.
  template      Start modeling from a template.
  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.
Copy

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

marketplace command

nextmv marketplace [command]
Copy

The marketplace command set is used to manage marketplace commands.

These are the available Marketplace Subcommands

CommandDescription
appA subsuite of commands to manage marketplace applications.
subscriptionA subsuite of commands to manage marketplace subscriptions

marketplace app subsuite

nextmv marketplace app [command]
Copy

Available marketplace app Subcommands

CommandDescription
createCreates a new marketplace application.
getGets a marketplace application.
listLists the marketplace applications.
updateUpdates a marketplace application.
versionCommands to manage marketplace application versions.

marketplace subscription subsuite

nextmv marketplace subscription [command]
Copy

Available marketplace subscription Subcommands

CommandDescription
createCreates a new marketplace subscription.
deleteDeletes a marketplace subscription.
getGets a marketplace subscription.
listLists the marketplace subscriptions.

template command

nextmv template [command]
Copy

The template command suite contains commands for interacting with templates.

These are the available subcommands for the template command:

SubcommandDescription
initInitialize a template locally. Learn more here.
listList the templates and/or their versions. Learn more here

init template subcommand

nextmv template init [flags]
Copy

The init subcommand initializes a template locally.

These are the available flags for the init subcommand:

FlagDescription
-t, --template stringThe name of the template you want to initialize locally.
-d, --directory stringThe directory in which to initialize the template.
-v, --version stringThe version of the template you want to initialize. If not provided, the "latest" version will be used.

list template subcommand

nextmv template list [flags]
Copy

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:

FlagDescription
-t, --template stringList the versions of the given template.
-f, --flat booleanFlat list of template's names. Flat list of an template's version when using the "template" flag.

update command

nextmv update [version] [flags]
Copy

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]
Copy

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

Page last updated

Go to on-page nav menu