Skip to content

Using secret collections

Info

Learn the concepts and fundamentals of secret collections in the Explanation page.

A secret collection defines one or more secrets used by your optimization model during execution. You can attach secret collections to an instance configuration, or directly when starting a run.

Included in this how-to guide are instructions on how to interact with the actions under the nextmv cloud secrets command tree. Go the reference section or use the --help option to see all the available options for each command.

Create a secrets collection

Use the nextmv cloud secrets create command to create a new secret collection for an application. You can create multiple secrets in the collection with the --secrets flag by:

  • Using the --secrets flag multiple times, or
  • Providing an array of objects in valid JSON format.

Each secret is defined as a JSON object with the following attributes:

  • type: Either env or file, which determines how the secret is injected into the runtime.
  • location: Where to place the secret.
    • env: the environment variable name. E.g.: BURROW_ENTRANCE.
    • file: the relative path from the execution directory. E.g.: licenses/burrow.entr.
  • value: The secret value as text (limited to 1 KB).
{
  "type": "env",
  "location": "ACME_LICENSE_KEY",
  "value": "abc123"
}

{
  "type": "file",
  "location": "config/app.conf",
  "value": "server=prod\nport=8080"
}

Here is an example command that uses both secrets defined above to create a secrets collection.

nextmv cloud secrets create \
    --app-id uncanny-rodent \
    --secrets '{"type": "env", "location": "ACME_LICENSE_KEY", "value": "abc123"}' \
    --secrets '{"type": "file", "location": "config/app.conf", "value": "server=prod\nport=8080"}'

⏳ Creating secrets collection...
{
  "id": "secrets-8k1x871l",
  "application_id": "uncanny-rodent",
  "name": "secrets-8k1x871l",
  "description": "",
  "created_at": "2026-07-23T21:15:35Z",
  "updated_at": "2026-07-23T21:15:35Z"
}

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

nextmv cloud secrets create \
    --app-id uncanny-rodent \
    --secrets '{"type": "env", "location": "ACME_LICENSE_KEY", "value": "abc123"}' \
    --secrets '{"type": "file", "location": "config/app.conf", "value": "server=prod\nport=8080"}' \
    --secrets-collection-id fluffy-secrets \
    --name "Secrets kept by a fluffy bunny"

⏳ Creating secrets collection...
{
  "id": "fluffy-secrets",
  "application_id": "uncanny-rodent",
  "name": "Secrets kept by a fluffy bunny",
  "description": "",
  "created_at": "2026-07-23T21:18:51Z",
  "updated_at": "2026-07-23T21:18:51Z"
}

Run with a secrets collection

Once a secrets collection has been created you can use it with the nextmv cloud run create command in two ways:

  • Use directly when starting a run with the --secret-collection-id flag, or
  • Attach it to an instance configuration with the --secrets-collection-id flag and use that instance when starting a run.

Here is an example where the secrets collection is used directly when starting a run.

nextmv cloud run create \
    --app-id uncanny-rodent \
    --input inputs \
    --secret-collection-id fluffy-secrets \
    --wait

✅ Run latest-2bJm4KEvR created.
⏳ Getting run results...
✅ Run outputs saved to latest-2bJm4KEvR-output. Here is the metadata.
{
  "description": "",
  "id": "latest-2bJm4KEvR",
  "metadata": {
    "application_id": "uncanny-rodent",
    "application_instance_id": "latest",
    "application_version_id": "",
    "created_at": "2026-07-23T21:23:59Z",
    "duration": 3975.0,
    "error": "",
    "execution_class": "6c9500mb870s",
    "execution_duration": 3476.0,
    "format": {
      "input": {
        "type": "multi-file"
      },
      "output": {
        "type": "multi-file"
      }
    },
    "initiated_at": "2026-07-23T21:23:59.620503Z",
    "input_size": 261.0,
    "metrics": {
      "metrics": {
        "message": "Hello, Patches",
        "value": 1.23
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "options_summary": [
        {
          "name": "details",
          "source": "version",
          "value": "true"
        }
      ]
    },
    "output_size": 159.0,
    "queuing_disabled": false,
    "queuing_priority": 6,
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "runtime": "python-3_11",
    "secrets_collection_id": "fluffy-secrets",
    "status_v2": "succeeded"
  },
  "name": "",
  "user_email": "sebastian@nextmv.io",
  "console_url": "https://cloud.nextmv.io/app/uncanny-rodent/run/latest-2bJm4KEvR?view=details"
}

Let's say we have an instance identified as production. First, let's update it to use the secrets collection.

nextmv cloud instance update \
    --app-id uncanny-rodent \
    --instance-id production \
    --secret-collection-id fluffy-secrets

⏳ 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",
    "secrets_collection_id": "fluffy-secrets",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-23T17:35:36.018490Z",
  "updated_at": "2026-07-23T21:30:59.869198Z"
}

We can now start a run using the production instance, and the secrets collection will be used automatically.

nextmv cloud run create \
    --app-id uncanny-rodent \
    --input inputs \
    --instance-id production \
    --wait

✅ Run production-3gPAVKPDg created.
⏳ Getting run results...
✅ Run outputs saved to production-3gPAVKPDg-output. Here is the metadata.
{
  "description": "",
  "id": "production-3gPAVKPDg",
  "metadata": {
    "application_id": "uncanny-rodent",
    "application_instance_id": "production",
    "application_version_id": "v0.0.1",
    "created_at": "2026-07-23T21:31:42Z",
    "duration": 6494.0,
    "error": "",
    "execution_class": "6c9500mb870s",
    "execution_duration": 5361.0,
    "format": {
      "input": {
        "type": "multi-file"
      },
      "output": {
        "type": "multi-file"
      }
    },
    "initiated_at": "2026-07-23T21:31:43.002336Z",
    "input_size": 261.0,
    "metrics": {
      "metrics": {
        "message": "Hello, Patches",
        "value": 1.23
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "options_summary": [
        {
          "name": "details",
          "source": "version",
          "value": "true"
        }
      ]
    },
    "output_size": 158.0,
    "queuing_disabled": false,
    "queuing_priority": 6,
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "runtime": "python-3_11",
    "secrets_collection_id": "fluffy-secrets",
    "status_v2": "succeeded"
  },
  "name": "",
  "user_email": "sebastian@nextmv.io",
  "console_url": "https://cloud.nextmv.io/app/uncanny-rodent/run/production-3gPAVKPDg?view=details"
}

Get a secrets collection

Use the nextmv cloud secrets get command to retrieve an existing secrets collection for an application by its ID.

Warning

The secret values will be shown in the output.

nextmv cloud secrets get --app-id uncanny-rodent --secrets-collection-id fluffy-secrets

⏳ Getting secrets collection...
{
  "id": "fluffy-secrets",
  "application_id": "uncanny-rodent",
  "name": "Secrets kept by a fluffy bunny",
  "description": "",
  "created_at": "2026-07-23T21:18:51Z",
  "updated_at": "2026-07-23T21:18:51Z",
  "secrets": [
    {
      "type": "env",
      "location": "ACME_LICENSE_KEY",
      "value": "abc123"
    },
    {
      "type": "file",
      "location": "config/app.conf",
      "value": "server=prod\nport=8080"
    }
  ]
}

You can list all collections in the application using the nextmv cloud secrets list command. The value of the secrets is omitted in the output.

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

⏳ Listing secrets collections...
[
  {
    "id": "fluffy-secrets",
    "application_id": "uncanny-rodent",
    "name": "Secrets kept by a fluffy bunny",
    "description": "",
    "created_at": "2026-07-23T21:18:51Z",
    "updated_at": "2026-07-23T21:18:51Z"
  },
  {
    "id": "secrets-8k1x871l",
    "application_id": "uncanny-rodent",
    "name": "secrets-8k1x871l",
    "description": "",
    "created_at": "2026-07-23T21:15:35Z",
    "updated_at": "2026-07-23T21:15:35Z"
  }
]

Update a secrets collection

You can update attributes of a secrets collection with the nextmv cloud secrets update command, such as its:

  • Name
  • Description
  • Secrets

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

When updating secrets, they will be completely replace with the new secrets provided. If you need to keep some of the existing secrets, you must include them in the update command. You cannot update the ID of a secrets collection.

nextmv cloud secrets update \
    --app-id uncanny-rodent \
    --secrets-collection-id fluffy-secrets \
    --secrets '{"type": "env", "location": "CARROT_KEY", "value": "delicious-vegetables"}'

⏳ Updating secrets collection...
✅ Secrets collection fluffy-secrets updated successfully in application uncanny-rodent.
{
  "id": "fluffy-secrets",
  "application_id": "uncanny-rodent",
  "name": "Secrets kept by a fluffy bunny",
  "description": "",
  "created_at": "2026-07-23T21:18:51Z",
  "updated_at": "2026-07-23T21:41:27Z"
}

Delete a secrets collection

Warning

Deleting a secrets collection is irreversible. All the secrets in the collection will be permanently deleted.

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

nextmv cloud secrets delete --app-id uncanny-rodent --secrets-collection-id fluffy-secrets

Are you sure you want to delete secrets collection fluffy-secrets from application uncanny-rodent? This action cannot be undone.
💡 Confirm Yes
✅ Secrets collection fluffy-secrets deleted successfully from application uncanny-rodent.