CLI

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

nextmv [command]

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

nextmv help

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

Global flags that can be added to any command.

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

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

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

nextmv app [command]

The app command manages and interacts with applications that you push and run in the Nextmv cloud. This feature is currently in public beta. Please contact support to request access.

These are the available subcommands of the app command:

nextmv app create [flags]

The app create command creates a new application. An application represents a problem you are solving, for example pizza delivery. It contains things like binaries, versions, and instances used in managing and running your application.

These are the available flags for the app create command:

Usage:

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

nextmv app get [flags]

The app get command gets the information related to an applications.

nextmv app list [flags]

The app list command lists all of the applications for your account.

Usage:

The app list-versions command lists all of the versions for an application.

Usage:

The app promote command creates a new version of an application from the last pushed binary, and assigns that version to the default instance.

Usage:

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

Usage:

The app result command 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 still in progress, then only metadata will be present in the results.

Usage:

The app run command starts a run of an application.

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

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

nextmv example-inputs <app type> [flags]

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:

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

nextmv example-inputs routing

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

tree routing-input-examples

nextmv help [command] [flags]

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:
  app            (Beta) Commands to manage and interact with your applications.
  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.
  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.

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

Usage:

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:

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

nextmv init -t knapsack

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

tree knapsack

nextmv install [version] [flags]

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:

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

nextmv private [command]

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

These are the available subcommands of the private command:

nextmv private bootstrap [flags]

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

nextmv private configure [flags]

The private configure command configures a private cloud environment.

These are the available flags for the private configure command:

nextmv private get-release [version] [flags]

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

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

nextmv private keys [command]

The private keys command manages the private cloud keys.

These are the available subcommands of the private keys command:

private keys create command

nextmv private keys create [flags]

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:

private keys deactivate command

nextmv private keys deactivate [flags]

The private keys deactivate command deactivates an enabled API key.

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

private keys list command

nextmv private keys list [flags]

The private keys list command lists API keys info.

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

private keys reactivate command

nextmv private keys reactivate [flags]

The private keys reactivate command reactivates a disabled API key.

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

nextmv private list-releases [flags]

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

nextmv run [command]

The run command is used to run a Nextmv application.

These are the available subcommands of the run command:

nextmv run local package [flags]

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:

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
# END HIDDEN SECTION
nextmv run local routing/main.go -- \
    -runner.input.path routing/input.json \
    -runner.output.path routing/output.json \
    -limits.duration 5s \

nextmv run result <runIDs> [flags]

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:

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

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

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

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

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

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

nextmv run status <runID> [flags]

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:

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

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

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:

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

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

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

nextmv token [flags]

The token command shows the current token used for authentication.

nextmv update [version] [flags]

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

nextmv version [flags]

The version command prints the Nextmv CLI version.

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.

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