Manage Cloud application instances¶

Info

Learn the concepts and fundamentals of instances in the Explanation page.

An application instance is a representation of a version and optional configuration (including options/parameters). Instances are the mechanism by which a run is made.

This how-to guide explains how to interact with the actions under the nextmv cloud instance command tree. Go the reference section or use the --help option to see all the available options for each command.

Create an instance¶

Use the nextmv cloud instance create command to create a new instance.

BashOutput

nextmv cloud instance create --app-id uncanny-rodent --version-id v0.0.1

⏳ Creating instance...
{
  "id": "instance-95gmvmdd",
  "application_id": "uncanny-rodent",
  "version_id": "v0.0.1",
  "name": "instance-95gmvmdd",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-23T17:33:14.984091Z",
  "updated_at": "2026-07-23T17:33:14.984091Z"
}

The command above will create a random ID, and use the same identifier for the instance's name. The name of the instance is used as a human-readable label. You can use the --instance-id and/or --name options to specify a custom ID and name for the instance. For example:

BashOutput

nextmv cloud instance create \
    --app-id uncanny-rodent \
    --version-id v0.0.1 \
    --instance-id production \
    --name "The main production instance"

⏳ Creating instance...
{
  "id": "production",
  "application_id": "uncanny-rodent",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-23T17:35:36.018490Z",
  "updated_at": "2026-07-23T17:35:36.018490Z"
}

In automated workflows, you don't have to check if an instance exists before creating it. Use the --exist-ok option to avoid an error if the instance already exists:

BashOutput

nextmv cloud instance create \
    --app-id uncanny-rodent \
    --version-id v0.0.1 \
    --instance-id production \
    --exist-ok

⏳ Creating or getting instance...
{
  "id": "production",
  "application_id": "uncanny-rodent",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-23T17:35:36.018490Z",
  "updated_at": "2026-07-23T17:35:36.018490Z"
}

You can configure the instance at the time of creation. Here are some of the available options:

--execution-class: the execution class to use for runs created on this instance.
--no-queuing: disable queuing for runs created on this instance.
--priority: set the queuing priority for runs created on this instance.
--options: the default options to use for runs created on this instance. The format for the option is key=value. You can pass multiple options by:
- Using the --options flag multiple times, or
- Using a comma-separated list of key-value pairs.

Please use the --help option on the nextmv cloud instance create command to see all the available options for configuring an instance. Consider the following example where an instance is created with the use of customized configuration:

BashOutput

nextmv cloud instance create \
    --app-id uncanny-rodent \
    --version-id v0.0.1 \
    --instance-id staging \
    --execution-class 8c16gb12h \
    --no-queuing \
    --priority 2 \
    --options "details=false"

⏳ Creating instance...
{
  "id": "staging",
  "application_id": "uncanny-rodent",
  "version_id": "v0.0.1",
  "name": "staging",
  "description": "",
  "configuration": {
    "execution_class": "8c16gb12h",
    "options": {
      "details": "false"
    },
    "queuing": {
      "priority": 2,
      "disabled": true
    }
  },
  "locked": false,
  "created_at": "2026-07-23T19:35:32.573197Z",
  "updated_at": "2026-07-23T19:35:32.573197Z"
}

Get an instance¶

Use the nextmv cloud instance get command to get an existing instance by its ID.

BashOutput

nextmv cloud instance get --app-id uncanny-rodent --instance-id production

⏳ Getting instance...
{
  "id": "production",
  "application_id": "uncanny-rodent",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-23T17:35:36.018490Z",
  "updated_at": "2026-07-23T17:35:36.018490Z"
}

You can list all instances in the application using the nextmv cloud instance list command. The same information is displayed as for the individual instances, but as an array of objects.

BashOutput

nextmv cloud instance list --app-id uncanny-rodent

⏳ Listing instances...
[
  {
    "id": "latest",
    "application_id": "uncanny-rodent",
    "version_id": "",
    "name": "Latest",
    "description": "Auto-created instance to manage the latest pushed executable binary.",
    "configuration": {
      "execution_class": "6c9500mb870s",
      "queuing": {
        "priority": 6,
        "disabled": false
      }
    },
    "locked": false,
    "created_at": "2026-07-22T23:22:41.148581Z",
    "updated_at": "2026-07-22T23:22:41.148581Z"
  },
  ...
  {
    "id": "production",
    "application_id": "uncanny-rodent",
    "version_id": "v0.0.1",
    "name": "The main production instance",
    "description": "",
    "configuration": {
      "execution_class": "6c9500mb870s",
      "queuing": {
        "priority": 6,
        "disabled": false
      }
    },
    "locked": false,
    "created_at": "2026-07-23T17:35:36.018490Z",
    "updated_at": "2026-07-23T17:35:36.018490Z"
  }
]

The latest instance is the default instance of an application and is automatically created when an application is created. The latest instance always point to the latest pushed executable. You cannot delete the latest instance.

For automated workflows, you can check if an instance exists with the nextmv cloud instance exists command. The command will return a zero exit code if the instance exists, and a non-zero exit code if it does not.

BashOutput

nextmv cloud instance exists --app-id uncanny-rodent --instance-id production

⏳ Checking if instance exists...
{
  "exists": true
}

Update an instance¶

You can update attributes of an instance and its configuration with the nextmv cloud instance update command, such as its:

Name
Description
Version ID
Execution class
Queuing priority
Locked status

Please use the --help option on the nextmv cloud instance update command to see all the available options for updating an instance. The options are similar to the ones available in the nextmv cloud instance create command.

To lock and unlock an instance, use the --locked and --unlocked options, respectively. You can only update the locked status of an instance when you update it, not when you create it.

You cannot update the instance ID. For the latest instance, you cannot update the version ID, as it is always associated to the latest pushed executable.

BashOutput

nextmv cloud instance update \
    --app-id uncanny-rodent \
    --instance-id production \
    --priority 9 \
    --options "details=true" \
    --locked

⏳ Updating instance...
✅ Instance production updated successfully in application uncanny-rodent.
{
  "id": "production",
  "application_id": "uncanny-rodent",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "options": {
      "details": "true"
    },
    "queuing": {
      "priority": 9,
      "disabled": false
    }
  },
  "locked": true,
  "created_at": "2026-07-23T17:35:36.018490Z",
  "updated_at": "2026-07-23T20:20:28.129834Z"
}

Delete an instance¶

Warning

Deleting an instance is irreversible. All the instance's data will be permanently deleted.

Info

You cannot delete the latest instance.
You cannot delete locked instances. You must unlock the instance before deleting it.

Delete an instance using the nextmv cloud instance delete command. The CLI will prompt you to confirm deletion but you can override it with the --yes option.

BashOutput

nextmv cloud instance delete --app-id uncanny-rodent --instance-id staging

Are you sure you want to delete instance staging from application uncanny-rodent? This action cannot be undone.
💡 Confirm Yes
✅ Instance staging deleted successfully from application uncanny-rodent.