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]

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

$ nextmv help

Usage:
  nextmv [command]

Available Commands:
  ...

Flags:
  ...

Use "nextmv [command] --help" for more information about a command.
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 ~/a/different/config.yaml
      
      Copy
    • -h, --help. This flag displays the help menu.

      $ nextmv -h
      
      Usage:
        nextmv [command]
      
      Available Commands:
        ...
      
      Flags:
        ...
      
      Use "nextmv [command] --help" for more information about a command.
      
      Copy

      You can also display the help for the specified command or subcommand. Here is an example using the version command:

      $ nextmv version -h
      
      Prints the Nextmv CLI version
      
      Usage:
        nextmv version [flags]
      
      Flags:
        -h, --help   help for version
      
      Global Flags:
        ...
      
      Copy

    build command

    nextmv build [packages] [flags]
    

    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 install
    checking go and sdk version support...
    downloading sdk files...
    successfully installed sdk files
    
    $ nextmv init -t routing
    Successfully generated the routing template in ...
    
    $ cd routing
    
    $ nextmv build main.go -o routing-app
    
    Copy

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

    .
    ├── README.md
    ├── go.mod
    ├── go.sum
    ├── input.json
    ├── license
    ├── main.go
    ├── routing.code-workspace
    └── routing-app
    
    Copy

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

    $ ./routing-app -h
    usage: ./routing-app
      -hop.runner.input.path string
            path to input file (default "-")
      -hop.runner.output.path string
            path to which output file should be written (default "-")
      ...
    
    Copy

    completion command

    nextmv completion [command]
    

    The completion command generates the autocompletion script for the Nextmv CLI for the specified shell.

    Here is an example where the completion command is used for zsh and macOS:

    1. If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

      echo "autoload -U compinit; compinit" >> ~/.zshrc
      
      Copy
    2. To load completions for every new session, execute once:

      nextmv completion zsh > $(brew --prefix)/share/zsh/site-functions/_nextmv
      
      Copy

    configure command

    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:

    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.

    $ nextmv configure -a <NEXTMV_API_KEY>
    Successfully updated configuration file: ~/.nextmv/config.yaml
    
    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]
    

    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
    Successfully generated example inputs for the routing app in ...
    
    $ cd routing-input-examples
    
    Copy

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

    .
    ├── README.md
    ├── distribution.json
    ├── tiny-delivery.json
    ├── tiny-fleet.json
    ├── delivery.json
    ├── fleet.json
    ├── tiny-distribution.json
    └── tiny-sourcing.json
    
    Copy

    help command

    nextmv help [command] [flags]
    

    The help command displays the main help menu.

    $ nextmv help
    
    Usage:
      nextmv [command]
    
    Available Commands:
      ...
    
    Flags:
      ...
    
    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
    Run your custom app locally.
    
    Usage:
      nextmv run local package [flags]
    
    Examples:
      ...
    
    Flags:
      ...
    
    Global Flags:
      ...
    
    Copy

    init command

    nextmv init [flags]
    

    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 install
    checking go and sdk version support...
    downloading sdk files...
    successfully installed sdk files
    
    $ nextmv init -t knapsack
    Successfully generated the knapsack template in ...
    
    $ cd knapsack
    
    Copy

    After initializing the template, you can check the contents of the knapsack dir:

    .
    ├── README.md
    ├── go.mod
    ├── go.sum
    ├── input.json
    ├── knapsack.code-workspace
    ├── license
    └── main.go
    
    Copy

    install command

    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:

    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 download the latest files and the Nextmv-managed Go executable:

    $ nextmv install
    checking go and sdk version support...
    Downloading go1.19.1.darwin-arm64.tar.gz ...
    ...
    
    Go go1.19.1 was installed into ~/.nextmv/go
    
    downloading sdk files...
    successfully installed sdk files
    
    Copy

    private command

    nextmv private [command]
    

    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]
    

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

    private configure command

    nextmv private configure [flags]
    

    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]
    

    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]
    

    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

      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:

      FlagDescription
      -a, --adminboolean
      -n, --name stringAPI key name.
    • private keys deactivate

      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:

      FlagDescription
      -a, --adminboolean
      -n, --name stringAPI key name.
    • private keys list

      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:

      FlagDescription
      -a, --allAll keys, including disabled ones.
    • private keys reactivate

      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:

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

    private list-releases command

    nextmv private list-releases [flags]
    

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

    run command

    nextmv run [command]
    

    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.

    nextmv run local package [flags]
    

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

    You must be inside your project when running this command. When running a Nextmv application, if no input path is given, you may provide input via stdin.

    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
    Successfully generated the routing template in ..
    
    $ cd routing
    
    $ nextmv run local main.go -- -hop.runner.input.path input.json \
      -hop.runner.output.path output.json \
      -hop.solver.limits.duration 5s
    
    Copy

    run result command

    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:

    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:

      nextmv run result <runID> --output
      
      Copy
    • The run result command can also retrieve multiple run results by passing multiple run IDs:

      nextmv run result <runID1> <runID2> <runID3>
      
      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:

      # 3 results returned in array
      $ nextmv run result <runID1> <runID2> <runID3> --array
      
      # 1 result returned in array
      $ nextmv run result <runID> --array
      
      Copy
    • If CSV format is specified, the results will be combined into a single CSV file:

      nextmv run result <runID1> <runID2> <runID3> --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 run ID specified:

      # file name will be multiple-runs-<runID1>.json
      nextmv run result <runID1> <runID2> <runID3> --output
      
      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:

      nextmv run result <runID> --poll --timeout 10
      
      Copy

    run status command

    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:

    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 and format is set to JSON:

    $ nextmv run status <runID> --format json
    {
      "status": "succeeded",
      "error": ""
    }
    
    Copy

    run submit command

    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:

    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.
    • This submits the input to Nextmv Cloud and returns the run ID:

      $ nextmv run submit --input <path/to/input.json> --runProfile <profile>
      {
        "runID": "45f3e1c6-..."
      }
      
      Copy

      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:

      nextmv run submit --input <path/to/input.json> --wait --runProfile <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.

      • For example, use the --format flag to specify the format of the returned result:

        nextmv run submit --input <path/to/input.json> --wait --format csv --runProfile <profile>
        
        Copy
      • Save the output directly to a file using the --output flag:

        nextmv run submit --input <path/to/input.json> --wait --format csv --output --runProfile <profile>
        
        Copy
      • When using the --wait flag, the process will, by default, poll run status for 60 seconds until timing out. This amount of time can be adjusted with the --timeout flag:

        nextmv run submit --input <path/to/input.json> --wait --timeout 10 --runProfile <profile>
        
        Copy

    token command

    nextmv token [flags]
    

    The token command shows the current token used for authentication.

    update command

    nextmv update [version] [flags]
    

    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]
    

    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