Nextmv CLI is a command line interface that you can use to interact with Nextmv.
To display more information about a command, use the help
command or one of the help global flags: --help
, -h
.
Available commands
Available commands and their corresponding subcommands. You can navigate to each section to learn more about the specific command.
Command | Description | Subcommands |
---|---|---|
app | (Beta) Manage and interact with applications you create here. | create , delete , get , list , list-versions , promote , push , result , run |
completion | Generate auto-completion script for a specified shell. Learn more here. | bash , fish , powershell , zsh |
configure | Setup Nextmv CLI. Learn more here. | |
example-inputs | Generate sample inputs for Nextmv remote apps. Learn more here. | |
help | Display help. Learn more here. | |
init | Generate a new model template. Learn more here. | |
install | Install the most recent or specified SDK version for your architecture. Learn more here. | |
private | Manage and interact with the Nextmv private cloud environment. Learn more here. | bootstrap , configure , get-release , keys , list-releases |
publish | Publishes the given app to the Nextmv cloud. (Coming Soon) | |
run | Run an application. Learn more here. | local , result , status , submit |
token | Print the current token. Learn more here. | |
update | Update Nextmv CLI. Learn more here. | |
version | Print the version of Nextmv CLI. Learn more here. |
Global Flags
Global flags that can be added to any command.
Flag | Description |
---|---|
-c , --config string | Full path to config file. |
-h , --help | Get 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 run
command:
-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:
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:
Subcommand | Description |
---|---|
create | Creates a new application in your account. here. |
delete | Deletes an application. Learn more here. |
get | Gets information about an application. Learn more here. |
list | Lists the applications in your account here. |
list-versions | Lists the versions for an application. Learn more here. |
promote | Creates a version from the most recently pushed binary. Learn more here. |
push | Pushes the binary from the current project to your application. Learn more here. |
result | Gets the result of an application run. Learn more here. |
run | Initiates a run of the application on the cloud. Learn more here. |
app-create
command
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:
Flag | Description |
---|---|
-a , --app-id string | (Required) 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 string | (Required) The name for the application. |
-d , --description string | (Optional) The description for the application. |
app-delete
command
The app delete
command deletes an application. When you delete an application all of the versions and instances are also deleted.
Flag | Description |
---|---|
-a , --app-id string | (Required) The id of the application to delete. |
app-get
command
The app get
command gets the information related to an applications.
Flag | Description |
---|---|
-a , --app-id string | (Required) The id of the application to get. |
app-list
command
The app list
command lists all of the applications for your account.
app-list-versions
command
The app list-versions
command lists all of the versions for an application.
Flag | Description |
---|---|
-a , --app-id string | (Required) The id of the application to list versions for. |
app-promote
command
The app promote
command creates a new version of an application from the last pushed binary, and assigns that version to the default instance.
Flag | Description |
---|---|
-a , --app-id string | (Required) The id of the application to promote. |
-n , --name string | (Optional) The name to assign to the version. Set to the app name + a unique ID if not specified |
-d , --description string | (Optional) The description for the version |
app-push
command
You must be inside your project when running this command.
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.
Flag | Description |
---|---|
-a , --app-id string | (Required) The id of the application to push to. |
app-result
command
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.
Flag | Description |
---|---|
-a , --app-id string | (Required) The id of the application for the run. |
-r , --run-id string | (Required) The id of the run. |
-o , --output string | (Optional) The output file to write. Stdout used if not specified. |
app-run
command
The app run
command starts a run of an application.
Flag | Description |
---|---|
-a , --app-id string | (Required) The id of the application to run. |
-i , --input string | (Optional) The input file to use (Stdin if not specified). |
-d , --input string | (Optional) Run the default instance. Runs the last pushed application binary if not specified. |
-w , --wait string | (Optional) Waits for the run to complete, and outputs results to stdout. |
-t , --timeout string | (Optional) The maximum time in seconds to poll for results (default 60 seconds). |
--instance string | (Optional)(Future) The id of the instance to use. |
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
:
configure
command
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:
Flag | Description |
---|---|
-a , --apiKey string | Nextmv API key. |
-s , --show | Prints the current configuration. |
Here is an example where the configure
command is used to update the Nextmv API key with an environment variable.
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
.
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:
Flag | Description |
---|---|
-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.
After generating the inputs, you can use the tree
command to check the contents of the routing-input-examples
dir:
help
command
The help
command displays the main help menu.
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:
init
command
The init
command initializes a new Nextmv template. A template is a ready-to-run application that solves a decision automation problem.
Available templates
Focus Area | Template | Description |
---|---|---|
vehicle routing | routing | Solves 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-routing | Solves 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. | |
packing | knapsack | Maximizes the total value without exceeding the weight capacity of the knapsack, given a collection of items with a value and weight. |
mip-knapsack | Solves the knapsack problem using Mixed Integer Programming and the open-source solver HiGHS. | |
scheduling | shift-scheduling | Assigns one worker to each shift while maximizing worker happiness score and covering all shifts with as few workers as possible. |
pager-duty | Assigns users to shifts (days) for incident response on-call duty using input and output data structures compatible with PagerDuty API. | |
custom | new-app | Provides a skeleton with guidance on how to utilize store to create a completely custom model. |
puzzle | sudoku | Fills a 9x9 grid such that all columns and all 3x3 subgrids contain the numerals 1 through 9. |
allocation | mip-meal-allocation | Allocates meals (diets) to bunnies with the goal of maximizing their happiness through good diets and nutrition. This template uses the open-source solver HiGHS. |
These are the available flags for the init
command:
Flag | Description |
---|---|
-d , --directory string | The directory in which to initialize the template. |
-t , --template string | The type of Nextmv template you wish to generate. |
Here is an example where the init
command is used to generate the knapsack
template.
After initializing the template, you can use the tree
command to check the contents of the knapsack
dir:
install
command
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:
Flag | Description |
---|---|
-g , --go string | The specific Go version used to execute the command, e.g.: go1.18.3 . See managing Go installations for more information. |
-r , --root string | The 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:
private
command
The private
command manages and interacts with the Nextmv private cloud environment.
These are the available subcommands of the private
command:
Subcommand | Description |
---|---|
bootstrap | Bootstrap the environment. Learn more here. |
configure | Configures the private cloud environment. Learn more here. |
get-release | Gets a private cloud release. Learn more here. |
keys | Keys commands. Learn more here. |
list-releases | Lists the available private cloud releases. Learn more here. |
private bootstrap
command
The private bootstrap
command bootstraps a new default admin configuration. A service url should be provided.
private configure
command
The private configure
command configures a private cloud environment.
These are the available flags for the private configure
command:
Flag | Description |
---|---|
-a , --apikey string | The API key used to make calls to the Nextmv private cloud. |
-e , --endpoint string | The host endpoint, e.g.: my.private.cloud.io:8402 . |
private get-release
command
The private get-release
command gets an installable release for a private deployment.
These are the available flags for the private get-release
command:
Flag | Description |
---|---|
-o , --output string | The directory to install to (default current). |
private keys
command
The private keys
command manages the private cloud keys.
These are the available subcommands of the private keys
command:
Subcommand | Description |
---|---|
create | Creates a new key. |
deactivate | Deactivates a key. |
list | List API keys info. |
reactivate | Reactivates a key. |
private keys create
command
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:
Flag | Description |
---|---|
-a , --admin | boolean |
-n , --name string | API key name. |
private keys deactivate
command
The private keys deactivate
command deactivates an enabled API key.
These are the available flags for the private keys deactivate
command:
Flag | Description |
---|---|
-a , --admin | boolean |
-n , --name string | API key name. |
private keys list
command
The private keys list
command lists API keys info.
These are the available flags for the private keys list
command:
Flag | Description |
---|---|
-a , --all | All keys, including disabled ones. |
private keys reactivate
command
The private keys reactivate
command reactivates a disabled API key.
These are the available flags for the private keys reactivate
command:
Flag | Description |
---|---|
-a , --admin | boolean |
-n , --name string | API key name. |
private list-releases
command
The private list-releases
command lists releases for private cloud.
run
command
The run
command is used to run a Nextmv application.
These are the available subcommands of the run
command:
Subcommand | Description |
---|---|
local | Run app locally. Learn more here. |
result | Get the result of a completed remote run. Learn more here. |
status | Get the status of a submitted remote run. Learn more here. |
submit | Submit 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
-- -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.
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:
Flag | Description |
---|---|
-d , --debugFlags | If set, this will insert -gcflags='all=-N -l' and -tags=debug to Go for debugging Nextmv applications. |
-g , --go string | The specific Go version used to execute the command, e.g.: go1.18.3 . See managing Go installations for more information. |
-r , --root string | The 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.
run result
command
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:
Flag | Description |
---|---|
-a , --array | If the format is JSON, then the result is always returned in an array. |
-f , --format string | Specifies the format of the returned result. Options are json (default) or csv . |
-o , --output | If 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 , --poll | Continuously poll until results are available. Default is false. |
-t , --timeout int | Set 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
.
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
.
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
.
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
.
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.
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
.
run status
command
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:
Flag | Description |
---|---|
-f , --format string | Controls 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:
run submit
command
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:
Flag | Description |
---|---|
-a , --array | If true, used with --wait , and --format is json , then the output is an array of run results. |
-f , --format string | Controls 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 , --input | The path to the input file to use. This flag is mandatory if data is not piped in through stdin . |
-o , --output | If 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 string | The run profile ID to use for the run. |
-t , --timeout int | Set timeout when polling in seconds. Default is 60 seconds. |
-w , --wait | Run 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.
Alternatively, the run submit
, run status
, and result
commands can be combined into a single command by adding the --wait
flag to run submit
.
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.
token
command
The token
command shows the current token used for authentication.
update
command
The update
command updates the Nextmv CLI. If the version is not specified, it will update to the latest one.
version
command
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 oflast
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 Flag | Environment Variable | Default | Description |
---|---|---|---|
-runner.input.path string | RUNNER_INPUT_PATH | - | Path to input file. |
-runner.output.path string | RUNNER_OUTPUT_PATH | - | Path to which output file should be written. |
-runner.output.quiet | RUNNER_OUTPUT_QUIET | null | Only output solutions. |
-runner.output.solutions string | RUNNER_OUTPUT_SOLUTIONS | last | Solutions to display: all , last - |
-runner.output.stream | RUNNER_OUTPUT_STREAM | null | Stream the output. |
-runner.profile.cpu string | RUNNER_PROFILE_CPU | null | File for CPU profile. |
-runner.profile.memory string | RUNNER_PROFILE_MEMORY | null | File for memory profile. |
-diagram.expansion.limit int | DIAGRAM_EXPANSION_LIMIT | 0 | Diagram expansion limit. |
-diagram.width int | DIAGRAM_WIDTH | 10 | Diagram width. |
-limits.duration duration | LIMITS_DURATION | 168h | Time limit, e.g. 10ms . |
-limits.nodes int | LIMITS_NODES | model.MaxInt | Node limit. |
-limits.solutions int | LIMITS_SOLUTIONS | model.MaxInt | Solution limit. |
-pool.size int | POOL_SIZE | 0 | Pool size (only used by specific engines). |
-random.seed int | RANDOM_SEED | 0 | Random seed. |
-search.buffer int | SEARCH_BUFFER | 100 | Solution 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.