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.

Secret values are write-only

Once a secret is set, its value cannot be retrieved. Every secret value is returned masked as ***************. The mask is literal and is always 15 * characters, regardless of the length or content of the secret value, so keep your own copy of any value you may need later.

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.

Info

Secret values are write-only. Every secret's value is returned as the masked placeholder ***************, while its type and location stay visible.

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": "***************"
    },
    {
      "type": "file",
      "location": "config/app.conf",
      "value": "***************"
    }
  ]
}

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.

The command uses the partial-update (PATCH) endpoint, so it never sends existing secret values back to Nextmv Cloud:

  • If you don't use --secrets, only the name and/or description are updated. The secrets in the collection are left as they are.
  • If you use --secrets, the provided secrets replace all the existing ones. Secrets with a matching type and location are updated, new ones are created, and existing secrets that you don't provide are deleted.
  • If you use --secrets together with --keep-existing, the provided secrets are updated or created, and existing secrets that you don't provide are kept.
  • Two secrets in --secrets can't have the same type and location.

You cannot update the ID of a secrets collection.

Upgrade the CLI before updating secrets collections

Secret values are write-only, so all updates to a secrets collection go through the partial-update (PATCH) endpoint. Older versions of the CLI use the deprecated full-collection update (PUT) endpoint instead. If you don't use --secrets, they get the collection and send its masked secret values back, so the request is rejected with a 400 Bad Request error. Upgrade to the latest version of the CLI.

Here is an example that renames a collection and leaves its secrets as they are.

nextmv cloud secrets update \
    --app-id uncanny-rodent \
    --secrets-collection-id fluffy-secrets \
    --name "Secrets kept by a very fluffy bunny"

⏳ 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 very fluffy bunny",
  "description": "",
  "created_at": "2026-07-23T21:18:51Z",
  "updated_at": "2026-07-23T21:41:19Z"
}

Here is an example that adds a secret and keeps the rest of the existing secrets.

nextmv cloud secrets update \
    --app-id uncanny-rodent \
    --secrets-collection-id fluffy-secrets \
    --keep-existing \
    --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 very fluffy bunny",
  "description": "",
  "created_at": "2026-07-23T21:18:51Z",
  "updated_at": "2026-07-23T21:41:27Z"
}

To replace all the secrets in the collection, leave out --keep-existing. The collection then contains only the secrets you provide.

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 very fluffy bunny",
  "description": "",
  "created_at": "2026-07-23T21:18:51Z",
  "updated_at": "2026-07-23T21:41:35Z"
}

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.