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
buildCompile code. Learn more here.
completionGenerate auto-completion script for a specified shell. Learn more here.bash, fish, powershell, zsh
configureSetup Nextmv CLI. Learn more here.
example-inputsGenerate sample inputs for Nextmv remote apps. Learn more here.
helpDisplay help. Learn more here.
initGenerate a new model template. Learn more here.
installInstall the most recent or specified SDK version for your architecture. Learn more here.
privateManage and interact with the Nextmv private cloud environment. Learn more here.bootstrap, configure, get-release, keys, list-releases
publishPublishes the given app to the Nextmv cloud. (Coming Soon)
runRun an application. Learn more here.local, result, status, submit
tokenPrint the current token. Learn more here.
updateUpdate Nextmv CLI. Learn more here.
versionPrint the version of Nextmv CLI. Learn more here.

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 build command:

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

build command

  nextmv build [packages] [flags]
Copy

The build command compiles the named main package that consumes SDK shared object files and the Nextmv SDK.

You must be inside your project when running this command.

These are the available flags for the build command:

FlagDescription
-d, --debugFlagsIf set, this will insert -gcflags='all=-N -l' and -tags=debug into Go for debugging Nextmv applications.
-g, --go stringThe specific Go version used to execute the command, e.g.: go1.18.3. See managing Go installations for more information.
-o, --output stringThe desired output path for the compiled binary.
-r, --root stringThe GOROOT used.

After compiling the binary, you can use runner and solver options directly.

Here is an example where the init and build commands are used to initialize a template. The binary is then compiled and named routing-app:

nextmv init -t routing
cd routing
nextmv build main.go -o routing-app
Copy

After compiling, you can use the tree command to check that a routing-app binary is now present in the routing dir:

tree routing
Copy

The runner and solver options can be displayed for the routing-app binary:

./routing/routing-app -h
Copy

Note that transient fields are represented with "<<PRESENCE>>", due to their dynamic nature: every time the input is run, these fields will have a different value. This representation is compliant with the jsonassert package.

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 --apiKey flag. This command is typically run once.

These are the available flags for the configure command:

FlagDescription
-a, --apiKey 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

example-inputs command

The example inputs are to be used with the Nextmv platform when running remotely. If you do not have access, contact support to request access.

Note, <app-type> is required with example-inputs.

  nextmv example-inputs <app type> [flags]
Copy

The example-inputs command generates example inputs for a Nextmv app and are meant to give examples of how to use the different features offered in that app for varying use cases.

These are the available flags for the example-inputs command:

FlagDescription
-d, --directory(Optional) The directory in which you'd like to generate the example input files.

Here is an example where the example-inputs command is used to generate sample inputs for the Nextmv routing app.

nextmv example-inputs routing
Copy

After generating the inputs, you can use the tree command to check the contents of the routing-input-examples dir:

tree routing-input-examples
Copy

help command

  nextmv help [command] [flags]
Copy

The help command displays the main help menu.


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

© 2019-2022 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:
  build          Compiles custom code consuming Nextmv's sdk package.
  completion     Generate the autocompletion script for the specified shell
  configure      Configure the Nextmv CLI.
  example-inputs Generate sample inputs for Nextmv remote apps.
  help           Help about any command
  init           Generate a new Nextmv model.
  install        Installs latest or specified version of sdk.
  private        Manage and interact with the Nextmv private cloud environment.
  publish        Publishes the given app to the Nextmv cloud (Coming Soon).
  run            Includes sub-commands to interact with remote and local runs.
  token          Shows the current token.
  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 run local command:

nextmv help run local
Copy

init command

Examples:
Copy

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

These are the available flags for the init command:

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 command is used to generate the knapsack template.

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

  nextmv install [version] [flags]
Copy

The install command 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 command:

FlagDescription
-g, --go stringThe specific Go version used to execute the command, e.g.: go1.18.3. See managing Go installations for more information.
-r, --root stringThe GOROOT used.

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

nextmv install
Copy

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.

private bootstrap command

  nextmv private bootstrap [flags]
Copy

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

private configure command

  nextmv private configure [flags]
Copy

The private configure command 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.

private get-release command

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

The private get-release command 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).

private keys command

  nextmv private keys [command]
Copy

The private keys command manages the private cloud keys.

These are the available subcommands of the private keys command:

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

private keys create command

  nextmv private keys create [flags]
Copy

The private keys create command creates a new key for admin and non-admin (applications).

These are the available flags for the private keys create command:

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

private keys deactivate command

  nextmv private keys deactivate [flags]
Copy

The private keys deactivate command deactivates an enabled API key.

These are the available flags for the private keys deactivate command:

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

private keys list command

  nextmv private keys list [flags]
Copy

The private keys list command lists API keys info.

These are the available flags for the private keys list command:

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

private keys reactivate command

  nextmv private keys reactivate [flags]
Copy

The private keys reactivate command reactivates a disabled API key.

These are the available flags for the private keys reactivate command:

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

private list-releases command

  nextmv private list-releases [flags]
Copy

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

run command

  nextmv run [command]
Copy

The run command is used to run a Nextmv application.

These are the available subcommands of the run command:

SubcommandDescription
localRun app locally. Learn more here.
resultGet the result of a completed remote run. Learn more here.
statusGet the status of a submitted remote run. Learn more here.
submitSubmit a remote run. Learn more here.

run local command

  • It is best practice to set a duration limit when running locally. Do this by passing the -- -hop.solver.duration.limit 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 run local package [flags]
Copy

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

These are the available flags for the run local command:

FlagDescription
-d, --debugFlagsIf set, this will insert -gcflags='all=-N -l' and -tags=debug to Go for debugging Nextmv applications.
-g, --go stringThe specific Go version used to execute the command, e.g.: go1.18.3. See managing Go installations for more information.
-r, --root stringThe GOROOT used.

Runner and solver options are passed using --.

Here is an example where the init and 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 init -t routing
nextmv run local routing/main.go -- \
    -hop.runner.input.path routing/input.json \
    -hop.runner.output.path routing/output.json \
    -hop.solver.limits.duration 5s \
    -hop.solver.diagram.expansion.limit 1
Copy

run result command

  nextmv run result <runIDs> [flags]
Copy

The run result command retrieves the result of a completed run specified by a runID. By default, the result will be printed directly to stdout.

These are the available flags for the run result command:

FlagDescription
-a, --arrayIf the format is JSON, then the result is always returned in an array.
-f, --format stringSpecifies the format of the returned result. Options are json (default) or csv.
-o, --outputIf true, creates a <runID>.<format> file in an output directory instead of sending result data to stdout. The output directory is created if it does not exist. Default value is false.
-p, --pollContinuously poll until results are available. Default is false.
-t, --timeout intSet timeout when polling in seconds. Default is 60 seconds.

To save the returned output in a file, use the --output flag. This will save the result in an output directory and the filename will be <runID>.json. (The output directory will be created if it doesn’t exist). If the run result is not available, a 404 error will be returned. You can use jq for example to visualize a key in the output. In the example, an environment variable is being used to read the runID.

nextmv run result $RUN_ID_1 --output
cat output/$RUN_ID_1.json | jq .state
Copy

The run result command can also retrieve multiple run results by passing multiple run IDs. As a default, the outputs are printed to stdout. You can use jq to visualize one of the keys for all outputs. In the example, environment variables are being used to read the multiple runIDs.

nextmv run result $RUN_ID_1 $RUN_ID_2 | jq .[].state
Copy

If the format is JSON, the results of each run will be returned in a single array. The result can be specified to always return in an array with the --array flag. We show how to use jq to get a specific key in the array and the example uses environment variables to specify the runIDs.

echo "=============== 1 result returned in array"
nextmv run result $RUN_ID_1  --array | jq .[].state
echo "=============== 2 results returned in array"
nextmv run result $RUN_ID_1 $RUN_ID_2 --array | jq .[].state
Copy

If CSV format is specified, the results will be combined into a single CSV file. You can use a tool such as miller to manipulate this CSV output. The example uses environment variables to specify the runIDs.

nextmv run result $RUN_ID_1 $RUN_ID_2 --format csv
Copy

When using the --output flag with multiple run IDs, the CLI will prefix the file name with a multiple-runs- slug followed by the first runID specified. The example uses environment variables to specify the runIDs and jq to visualize a key across all outputs.

nextmv run result $RUN_ID_1 $RUN_ID_2 --output
cat output/multiple-runs-$RUN_ID_1.json | jq .[].state
Copy

To have run result continuously poll until results are available, add the --poll flag (default behavior is to not poll). The --timeout flag can be used with the --poll flag to adjust the polling duration. The example uses an environment variable to specify the runID.

nextmv run result $RUN_ID_1 --poll --timeout 10
Copy

run status command

  nextmv run status <runID> [flags]
Copy

The run status command checks the status o f a submitted run specified by a runID.

These are the available flags for the run status command:

FlagDescription
-f, --format stringControls the format of stdout. The only supported option is json.

Here is an example where the run status command is used to check the status of a runID (read from an environment variable), and the format is set to JSON:

nextmv run status $RUN_ID_1 --format json
Copy

run submit command

  nextmv run submit < -i | stdin > [flags]
Copy

The run submit command submits an input file to Nextmv Cloud and starts a run. Note, the -p, --runProfile string flag is required for every run and the --input|-i flag is mandatory if data is not piped in through stdin.

These are the available flags for the run submit command:

FlagDescription
-a, --arrayIf true, used with --wait, and --format is json, then the output is an array of run results.
-f, --format stringControls the format of a run result. If used with --wait, supported options are json and csv. If used without --wait, the only supported option is json. If an unsupported format is given the output is json.
-i, --inputThe path to the input file to use. This flag is mandatory if data is not piped in through stdin.
-o, --outputIf true, creates a <runID>.<format> file in an output directory instead of sending result data to stdout. The output directory is created if it does not exist. Default value is false.
-p, --runProfile stringThe run profile ID to use for the run.
-t, --timeout intSet timeout when polling in seconds. Default is 60 seconds.
-w, --waitRun complete process including submit, polling for results, and results retrieval on success.

For example, the following command submits the input to Nextmv Cloud and returns the runID, using a specific run profile. The input is read from some input.json file. The returned format for the standard run submit command is always JSON.

nextmv run submit --input input.json --runProfile test-profile
Copy

Alternatively, the run submit, run status, and result commands can be combined into a single command by adding the --wait flag to run submit.

nextmv run submit --input input.json --wait --runProfile test-profile
Copy

When the status returns completed, this submits the input, retrieves the run ID, polls the status, and then returns a success message. When the --wait flag is used, then all of the flags and functionality associated with run result are made available to run submit.

The following snippet shows example commands where the run result flags are passed to the run submit comamnd.

# Use the `--format` flag to specify the format of the returned result.
nextmv run submit --input input.json --wait --format csv --runProfile test-profile

# Save the output directly to a file using the `--output` flag.
nextmv run submit --input input.json --wait --format csv --output --runProfile test-profile

# Modify the time the process polls for until timing out.
nextmv run submit --input input.json --wait --timeout 10 --runProfile test-profile
Copy

token command

  nextmv token [flags]
Copy

The token command shows the current token used for authentication.

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

-hop.solver.limits.solutions is equivalent to HOP_SOLVER_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
-hop.runner.input.path stringHOP_RUNNER_INPUT_PATH-Path to input file.
-hop.runner.output.path stringHOP_RUNNER_OUTPUT_PATH-Path to which output file should be written.
-hop.runner.output.quietHOP_RUNNER_OUTPUT_QUIETnullOnly output solutions.
-hop.runner.output.solutions stringHOP_RUNNER_OUTPUT_SOLUTIONSlastSolutions to display: all, last-
-hop.runner.output.streamHOP_RUNNER_OUTPUT_STREAMnullStream the output.
-hop.runner.profile.cpu stringHOP_RUNNER_PROFILE_CPUnullFile for CPU profile.
-hop.runner.profile.memory stringHOP_RUNNER_PROFILE_MEMORYnullFile for memory profile.
-hop.solver.diagram.expansion.limit intHOP_SOLVER_DIAGRAM_EXPANSION_LIMIT0Diagram expansion limit.
-hop.solver.diagram.width intHOP_SOLVER_DIAGRAM_WIDTH10Diagram width.
-hop.solver.limits.duration durationHOP_SOLVER_LIMITS_DURATION168hTime limit, e.g. 10ms.
-hop.solver.limits.nodes intHOP_SOLVER_LIMITS_NODESmodel.MaxIntNode limit.
-hop.solver.limits.solutions intHOP_SOLVER_LIMITS_SOLUTIONSmodel.MaxIntSolution limit.
-hop.solver.pool.size intHOP_SOLVER_POOL_SIZE0Pool size (only used by specific engines).
-hop.solver.random.seed intHOP_SOLVER_RANDOM_SEED0Random seed.
-hop.solver.search.buffer intHOP_SOLVER_SEARCH_BUFFER100Solution buffer (0 = none).

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

HOP_SOLVER_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 HOP_SOLVER_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