Skip to content

Quick start with the Nextmv CLI

⌛️ Approximate time to complete: 5 min.

In this tutorial you will learn how to use the Nextmv CLI, in particular, the nextmv init command, to scaffold a Nextmv application, run it locally, and inspect the results. Complete this tutorial if you:

  • Are new to Nextmv and want the fastest path to a working app.

At a high level, this tutorial will go through the following steps:

  1. Install the Nextmv CLI.
  2. Scaffold an app with nextmv init.
  3. Inspect the scaffolded files.
  4. Run the app locally.
  5. Get the results.

Let's dive right in 🤿.

1. Install the Nextmv CLI

Please see the Nextmv CLI installation guide.

2. Run nextmv init

The nextmv init command interactively scaffolds a new Nextmv application. Run it from the directory where you want to create your app:

nextmv init

We suggest walking through the prompts with the following answers, as they provide an interesting example to explore the Nextmv platform:

  1. Language.

    • Question: Which type (language) do you want to work with?
    • Answer: python

  2. Example vs. existing model

    • Question: How do you want to start working with Nextmv?
    • Answer: Example - class-room assignment

  3. Content format.

    • Question: Which type of I/O (input/output) content format do you prefer for your app?
    • Answer: json

  4. Initialization path.

    • Question: Where would you like to initialize your Nextmv application template?
    • Answer: .

After these prompts, the CLI scaffolds a new Nextmv application in the current directory. You should see a message similar to the following:

✅ python, json template initialized at /your/path/python_json_class-assign.

Warning

Do not close the terminal or interrupt the process at this point. This tutorial will continue with more steps after the scaffolding is complete.

You can inspect the python_json_class_assign directory and see the following files:

.
├── app.yaml
├── input.json
├── main.py
├── pyproject.toml
├── README.md
├── uv.lock
└── visualizations.py

The two most important files are:

  • app.yaml: the app manifest. It tells the Nextmv CLI which files belong to your app, the runtime to use, and what options are available.
  • main.py: the entrypoint. The default template reads data from stdin and returns a solution. Replace this logic with your own decision model.

3. Continue with nextmv init to run the app locally

At this point, the CLI has scaffolded a new Nextmv application and it will give you a few more prompts. We suggest walking through the prompts with the following answers:

  1. Starting a local run.

    • Question: Do you want to start a run for local app at /your/path/python_json_class-assign now?
    • Answer: Yes

    You will note that the CLI will change directories into the app's dir.

    ⏳ Changing working directory with command: cd /your/path/python_json_class-assign
✅ Working directory is now /your/path/python_json_class-assign.

  2. Input selection.

    • Question: Please select a directory or file to use as input for the local run
    • Answer: input.json

    You will see the command used to create the local run and the resulting run ID.

    ⏳ Starting local run with command: nextmv local run create --input input.json
{
  "run_id": "local-g1xw41k4"
}
✅ Local run started successfully with run ID: local-g1xw41k4.

  3. Getting the results of the local run.

    • Question: Do you want to get the results of the local run with ID local-g1xw41k4 now?
    • Answer: Yes

    You will see the command used to get the results of the local run and the actual results.

    ⏳ Getting local run results with command: nextmv local run get --run-id local-g1xw41k4 --wait
⏳ Getting run results...
💡 Removed assets from output for cleaner display, use --output to save the full output.
{
  "description": "Local run created at 2026-07-01T23:57:34.892504Z",
  "id": "local-g1xw41k4",
  "metadata": {
    "application_id": "local-app-dl08rhvj",
    "application_instance_id": "",
    "application_version_id": "",
    "created_at": "2026-07-01T23:57:34.892504Z",
    "duration": 5877.0,
    "error": "",
    "execution_class": "local",
    "execution_duration": 5877.0,
    "experiment_id": "",
    "experiment_type": "",
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "initiated_at": "2026-07-01T23:57:34.892504Z",
    "input_size": 7003.0,
    "metrics": {
      "value": 137.5,
      ...
    },
    "options": {
      "active_options": {},
      "options_summary": [],
      "request_options": {}
    },
    "output_size": 0.0,
    "queuing_disabled": true,
    "queuing_priority": 0,
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "runtime": "local",
    "secrets_collection_id": "",
    "status_v2": "succeeded",
    "tracking": {
      "cloned_run_id": "",
      "input_id": ""
    }
  },
  "name": "local run local-g1xw41k4",
  "user_email": "",
  "console_url": "",
  "output": {
    "options": {
      "duration": 30,
      "extended_day_time": 17,
      "extended_day_bonus": 2.0,
      "extended_day_penalty": 0.5
    },
    "solution": {
      "assignments": [
        {
          "student_id": "s1",
          "class_id": "hon-stem-1",
          "student_name": "Alice Johnson",
          "class_name": "Honors STEM A",
          "subject_focus": "STEM",
          "focus_preference_match": true,
          "extended_day_requested": 16,
          "extended_day_granted": true
        },
        ...
      ],
      "unassigned": [],
      "total_assigned": 25,
      "total_students": 25
    },
    "metrics": {
      "value": 137.5,
      ...
    }
  }
}

Success

At this point, you can choose to not continue with the prompts. You have successfully run your application locally 🥳.

4. Next steps

You now have a working Nextmv application running locally. From here you can:

  • Replace the template logic in main.py with your own decision model.
  • Activate a plan with Nextmv and explore our Cloud platform.

For more detailed walkthroughs, check out these tutorials:

🎉🎉🎉 Congratulations, you have finished this tutorial!