Reference

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.

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
activateActivate nextmv CLI.
appManage and interact with applications you create.create, delete, get, list, list-versions, promote, push, result, run, metadata
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.batch, input-set
helpDisplay help.
privateManage and interact with the Nextmv private cloud environment.bootstrap, configure, get-release, keys, list-releases
sdkInstall dev tools, initialize optimization templates and run models locallyinit, install, run
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). Here is an example using the sdk run command:

nextmv sdk run main.go -c ~/.nextmv/another-config.yaml
Copy

-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

activate command

nextmv activate [flags]
Copy

Note: Tokens auto-renew, and there is no longer an activation required to extend a token

If you receive an error message containing "Your token expired and couldn't be updated" it is advised to run the activate command. In case of any questions or issues, please contact support.

app command

nextmv app [command]
Copy

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

Experiments is a beta feature and not intended for production use. To try out experiments with Nextmv, you must have a Nextmv account and be signed up for a production 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
batchA subsuite of commands to start batch experiments
input-setA subsuite of commands to manage input sets

batch subcommand

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

CommandDescriptionFlags
startStart a batch experiment--app-id, --experiment-id, --description, --name, --input-set-id, --instance-ids

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

input-set subcommand

Input sets are used to define named groups of 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

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

help command

nextmv help [command] [flags]
Copy

The help command displays the main help menu.


--------------------------------------------------------------------------------
This software is provided by Nextmv.

© 2019-2023 nextmv.io inc. All rights reserved.

    (\/)     (\/)     (\/)     (\/)     (\/)     (\/)     (\/)     (\/)     (\/)
    (^^)     (^^)     (^^)     (^^)     (^^)     (^^)     (^^)     (^^)     (^^)
   o( O)    o( O)    o( O)    o( O)    o( O)    o( O)    o( O)    o( O)    o( O)
--------------------------------------------------------------------------------

Usage:
  nextmv [command]

Available Commands:
  activate    Activate nextmv CLI.
  app         Commands to manage and interact with your applications.
  completion  Generate the autocompletion script for the specified shell
  configure   Configure the Nextmv CLI.
  experiment  Commands to run and manage experiments (beta).
  go          Provides passthrough access to the packaged Go toolchain.
  help        Help about any command
  private     Manage and interact with the Nextmv private cloud environment.
  sdk         Install dev tools, initialize optimization templates and run models locally.
  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.

Here is an example where the help command is used to display the help for the sdk run command:

nextmv help sdk run
Copy

go command

nextmv go [go command] [arguments] [flags]
Copy

The go command provides a passthrough to the Nextmv-managed Go toolchain.

private command

nextmv private [command]
Copy

The private command manages and interacts with the Nextmv private cloud environment.

These are the available subcommands of the private command:

SubcommandDescription
bootstrapBootstrap the environment. Learn more here.
configureConfigures the private cloud environment. Learn more here.
get-releaseGets a private cloud release. Learn more here.
keysKeys commands. Learn more here.
list-releasesLists the available private cloud releases. Learn more here.

bootstrap subcommand

nextmv private bootstrap [flags]
Copy

The bootstrap subcommand bootstraps a new default admin configuration. A service url should be provided.

configure subcommand

nextmv private configure [flags]
Copy

The configure subcommand configures a private cloud environment.

These are the available flags for the private configure command:

FlagDescription
-a, --apikey stringThe API key used to make calls to the Nextmv private cloud.
-e, --endpoint stringThe host endpoint, e.g.: my.private.cloud.io:8402.

get-release subcommand

nextmv private get-release [version] [flags]
Copy

The get-release subcommand gets an installable release for a private deployment.

These are the available flags for the private get-release command:

FlagDescription
-o, --output stringThe directory to install to (default current).

keys subcommand

nextmv private keys [command]
Copy

The keys subcommand manages the private cloud keys.

These are the available subcommands of the nextmv private keys command:

SubcommandDescription
createCreates a new key.
deactivateDeactivates a key.
listList API keys info.
reactivateReactivates a key.

create subcommand

nextmv private keys create [flags]
Copy

The create subcommand creates a new key for admin and non-admin (applications).

These are the available flags for the create subcommand:

FlagDescription
-a, --adminboolean
-n, --name stringAPI key name.

deactivate subcommand

nextmv private keys deactivate [flags]
Copy

The deactivate subcommand deactivates an enabled API key.

These are the available flags for the deactivate command:

FlagDescription
-a, --adminboolean
-n, --name stringAPI key name.

keys list subcommand

nextmv private keys list [flags]
Copy

The list subcommand lists API keys info.

These are the available flags for the list subcommand:

FlagDescription
-a, --allAll keys, including disabled ones.

reactivate subcommand

nextmv private keys reactivate [flags]
Copy

The reactivate subcommand reactivates a disabled API key.

These are the available flags for the reactivate subcommand:

FlagDescription
-a, --adminboolean
-n, --name stringAPI key name.

list-releases subcommand

nextmv private list-releases [flags]
Copy

The private list-releases command lists releases for private cloud.

sdk command

nextmv sdk [command]
Copy

The sdk command suite contains commands for downloading and using Nextmv plugins for local development.

These are the available subcommands for the sdk command:

SubcommandDescription
initInitialize a new Nextmv template. Learn more here.
installInstalls Nextmv plugin dependencies. Learn more here
runRun app locally. Learn more here.

init subcommand

nextmv sdk init [flags]
Copy

The init subcommand initializes a new Nextmv template. A template is a ready-to-run application that solves a decision automation problem.

Available templates

Focus AreaTemplateDescription
vehicle routingroutingSolves a vehicle routing problem (VRP), using the Nextmv Router Engine. The template includes a complete list of options that can easily be configured to solve most routing problems.
cloud-routingSolves a vehicle routing problem (VRP), using a different input structure than the template above that exposes constraints via the input file. This template is the basis for the Nextmv routing app.
routing-matrix-inputA modeling kit for vehicle routing problems (VRP). This template shows how to use a custom matrix that is passed via an input file
measure-matrixServes as an input generator for the routing-matrix-input app. The generated input data includes matrices for distance and travel time
time-dependent-measureMakes use of time dependent measures and applies different costs according to time.
unique-matrix-measureReduce input file size by limiting the stop matrix to just unique points.
clusteringclusterGroups a set of data points into clusters, where each cluster is a collection of points that are similar to one another in some way.
cluster-tspCreates a set of clusters equal to the number of vehicles, in a pre-processing step, then solves a TSP for each vehicle.
packingknapsackMaximizes the total value without exceeding the weight capacity of the knapsack, given a collection of items with a value and weight.
mip-knapsackSolves the knapsack problem using Mixed Integer Programming and the open-source solver HiGHS.
schedulingshift-schedulingAssigns one worker to each shift while maximizing worker happiness score and covering all shifts with as few workers as possible.
pager-dutyAssigns users to shifts (days) for incident response on-call duty using input and output data structures compatible with PagerDuty API.
customnew-appProvides a skeleton with guidance on how to utilize store to create a completely custom model.
puzzlesudokuFills a 9x9 grid such that all columns and all 3x3 subgrids contain the numerals 1 through 9.
allocationmip-meal-allocationAllocates meals (diets) to bunnies with the goal of maximizing their happiness through good diets and nutrition. This template uses the open-source solver HiGHS.

For a more in depth understanding of how to use each of these templates, visit the SDK reference page.

These are the available flags for the init subcommand:

FlagDescription
-d, --directory stringThe directory in which to initialize the template.
-t, --template stringThe type of Nextmv template you wish to generate.

Here is an example where the init subcommand is used to generate the knapsack template.

nextmv sdk init -t knapsack
Copy

After initializing the template, you can use the tree command to check the contents of the knapsack dir:

tree knapsack
Copy

install subcommand

nextmv sdk install [version] [flags]
Copy

The install subcommand downloads the latest version of the SDK shared object files (or the version specified, if given) and the Nextmv-managed Go executable for your architecture.

These are the available flags for the install subcommand:

FlagDescription
-r, --root stringThe GOROOT used.

Here is an example where the install subcommand is used to check that all the necessary files and the Nextmv-managed Go executable are already installed:

nextmv sdk install
Copy

run subcommand

  • It is best practice to set a duration limit when running locally. Do this by passing the -- -limits.duration flag. You can read more about solver flags here.
  • When running a Nextmv application, if no input path is given, you may provide input via stdin.
nextmv sdk run package [flags]
Copy

The run subcommand allows you to compile and run custom code consuming the Nextmv SDK.

These are the available flags for the run subcommand:

FlagDescription
-d, --debug-flagsIf set, this will insert -gcflags='all=-N -l' and -tags=debug to Go for debugging Nextmv applications.
-r, --root stringThe GOROOT used.

Runner and solver options are passed using --.

Here is an example where the sdk init and sdk run commands are used to run the routing template. The input is read from the input.json file and the output is saved to an output.json file.

nextmv sdk init -t routing
nextmv sdk run routing/main.go -- \
    -runner.input.path routing/input.json \
    -runner.output.path routing/output.json \
    -limits.duration 5s \
Copy

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.

Runner and solver options

All applications are configurable through the following options.

  • Runner options change how the runner outputs solutions. For instance, -runner.output.solutions default of last will only output the final improving solution in a decision automation model.
  • Solver options change how many states are allowed in a diagram, how many states it pulls from the search queue, termination criteria, and randomization.

Options can be configured as CLI flags or environment variables. To set an environment variable, convert its corresponding CLI flag to uppercase, replacing each period (.) with an underscore (_) and removing the leading dash (-). For example:

-limits.solutions is equivalent to LIMITS_SOLUTIONS.

If both an environment variable and its corresponding CLI flag are defined, the CLI flag will overwrite the environment variable.

CLI FlagEnvironment VariableDefaultDescription
-runner.input.path stringRUNNER_INPUT_PATH-Path to input file.
-runner.output.path stringRUNNER_OUTPUT_PATH-Path to which output file should be written.
-runner.output.quietRUNNER_OUTPUT_QUIETnullOnly output solutions.
-runner.output.solutions stringRUNNER_OUTPUT_SOLUTIONSlastSolutions to display: all, last-
-runner.output.streamRUNNER_OUTPUT_STREAMnullStream the output.
-runner.profile.cpu stringRUNNER_PROFILE_CPUnullFile for CPU profile.
-runner.profile.memory stringRUNNER_PROFILE_MEMORYnullFile for memory profile.
-diagram.expansion.limit intDIAGRAM_EXPANSION_LIMIT0Diagram expansion limit.
-diagram.width intDIAGRAM_WIDTH10Diagram width.
-limits.duration durationLIMITS_DURATION168hTime limit, e.g. 10ms.
-limits.nodes intLIMITS_NODESmodel.MaxIntNode limit.
-limits.solutions intLIMITS_SOLUTIONSmodel.MaxIntSolution limit.
-pool.size intPOOL_SIZE0Pool size (only used by specific engines).
-random.seed intRANDOM_SEED0Random seed.
-search.buffer intSEARCH_BUFFER100Solution buffer (0 = none).

Solver options are automatically marshaled into model output in the options section of the JSON.

LIMITS_DURATION should be set to a non-zero value in production i.e. 1h or 1m30s. Valid time units are as follows, according to time.ParseDuration from Go's standard library.

  • ns (nanoseconds)
  • us/µs (microseconds)
  • ms (milliseconds)
  • s (seconds)
  • m (minutes)
  • h (hours)

The POOL_SIZE variable is only used by specific engines, e.g. the fleet engine. In the specific case of the fleet engine, the larger value of runtime.GOMAXPROCS(0) / 2 and 1 overrides the POOL_SIZE default value.

Page last updated

Go to on-page nav menu