> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# Manage Patch Envelopes

> Use ZCLI commands to create, view, update, activate, and delete patch envelopes that deliver files to running application instances.

Use the ZEDEDA CLI (ZCLI) to manage patch envelopes from the command line. This article covers `zcli patch-envelope` commands, with syntax and examples for each operation.

A patch envelope is a versioned bundle of files, called artifacts, that Edge Infrastructure Services delivers to running application instances without redeploying them. Each patch envelope belongs to one project. An artifact is one of the following:

* An **inline** artifact, which embeds a base64-encoded payload directly in the patch envelope.
* An **external** artifact, which references a patch artifact image that is stored in a datastore. Use external artifacts for larger files.

Delivering files with a patch envelope takes the following steps:

1. For external artifacts, create a patch artifact image and add its file. See [Create the Patch Artifact Image](#create-the-patch-artifact-image).
2. Describe the artifacts in an artifact configuration file. See [Write the Artifact Configuration File](#write-the-artifact-configuration-file).
3. Create the patch envelope with `zcli patch-envelope create`.
4. Attach the patch envelope to application instances with `zcli edge-app-instance patch-envelope-attach`. See [Attach a Patch Envelope to Application Instances](#attach-a-patch-envelope-to-application-instances).
5. Set the patch envelope to the active state, if you did not create it active.

For the console procedures and background, see [Update Applications with Runtime Bundles](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/update-applications-with-runtime-bundles.md) and [Patch Envelopes](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/patch-envelopes.md).

## Before You Start

* ZCLI is installed and authenticated against your enterprise. See [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md).
* You have the SysManager or SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md).
* The project that the patch envelope belongs to already exists. See [Manage Projects](https://zededa.mintlify.site/zcli-reference/projects.md).
* The application instances that will receive the patch envelope belong to that project.

## Patch Envelope States

The `--action` flag sets the state of a patch envelope. The console calls these states Active and Stored.

| `--action` value | Console state | Description |
| - | - | - |
| `activate` | Active | The patch envelope delivers its artifacts to every application instance it is attached to. |
| `store` | Stored | The patch envelope is saved but does not deliver. Attached application instances do not receive its artifacts while it is stored. |

ZCLI accepts the values in any letter case. Any other value prints `Invalid value for --action parameter. Value should either be "store" or "activate"` and ZCLI does not send the request.

## Prepare the Artifacts

### Create the patch artifact image

Skip this step if all your artifacts are inline.

An external artifact references an image that you create with the `--patch-artifact-image` flag. Create the image record, then upload or uplink its file.

1. Create the image record:

   ```bash theme={"dark"}
   zcli image create MY_PATCH_ARTIFACT --datastore-name=MY_DATASTORE --patch-artifact-image --image-format=raw
   ```

2. Upload the file:

   ```bash theme={"dark"}
   zcli image upload MY_PATCH_ARTIFACT --path=./my-config-update.tar
   ```

Wait for the image status to change to `READY`. Then find the image ID, which the artifact configuration file needs:

```bash theme={"dark"}
zcli image show MY_PATCH_ARTIFACT --detail
```

The ID appears in the `Image ID` field. For details about patch artifact images, upload, and uplink, see [Manage Images](https://zededa.mintlify.site/zcli-reference/images.md).

### Write the artifact configuration file

`zcli patch-envelope create` reads the artifacts from a JSON file that you pass with `--artifact-config-file`. The file contains an `artifacts` list with one object for each artifact. The following example contains one external artifact and one inline artifact:

```json theme={"dark"}
{
    "artifacts": [
        {
            "format": "OpaqueObjectCategoryExternalBinary",
            "binaryArtifact": {
                "imageName": "MY_PATCH_ARTIFACT",
                "imageId": "<image-id>",
                "fileNameToUse": "my-config-update.tar",
                "blobMetaData": "<blob-metadata>"
            },
            "artifactMetaData": "<artifact-metadata>",
            "id": "<artifact-id>"
        },
        {
            "format": "OpaqueObjectCategoryInline",
            "base64Artifact": {
                "base64Data": "YXJ0aWZhY3QgZGF0YQ==",
                "fileNameToUse": "settings.txt",
                "base64MetaData": "YXJ0aWZhY3QgbWV0YWRhdGE="
            },
            "artifactMetaData": "YXJ0aWZhY3QgbWV0YWRhdGE=",
            "id": "<artifact-id>"
        }
    ]
}
```

| Field | Description |
| - | - |
| `format` | `OpaqueObjectCategoryExternalBinary` for an external artifact, or `OpaqueObjectCategoryInline` for an inline artifact. |
| `binaryArtifact` | External artifacts only. `imageName` and `imageId` identify the patch artifact image. `fileNameToUse` is the file name the artifact is written as. `blobMetaData` is optional metadata for the file. |
| `base64Artifact` | Inline artifacts only. `base64Data` is the file content, base64-encoded. `fileNameToUse` is the file name the artifact is written as. `base64MetaData` is optional metadata. |
| `artifactMetaData` | Optional metadata for the artifact. |
| `id` | Artifact ID. \[TBD: confirm whether `id` is required in the artifact configuration file, and whether you supply a UUID or Edge Infrastructure Services generates one. ZCLI's own test file supplies a UUID.] |

To base64-encode a file for `base64Data`, run `base64 -i settings.txt` on macOS or `base64 -w 0 settings.txt` on Linux.

> [!NOTE]
>
> ZCLI sends the contents of the `artifacts` list exactly as written. It does not check the `format` values, encode the inline data, or look up the image ID from `imageName`. Copy the image ID from `zcli image show --detail`, and encode inline data yourself before you create the patch envelope.

> [!NOTE]
>
> ZCLI includes a sample artifact configuration file, `patch-artifact-config.tmpl`, but the sample has a trailing comma after the last artifact, which is not valid JSON. If you start from that sample, remove the trailing comma. ZCLI has no command to copy the sample, so the preceding example is a simpler starting point.

## Create a Patch Envelope

Create a patch envelope in a project from an artifact configuration file.

```bash theme={"dark"}
zcli patch-envelope create <name> --title=<title> --user-defined-version=<user-defined-version> --action=<action> --project-name=<project-name> --artifact-config-file=<file-path> [--description=<description>]
```

| Flag | Description |
| - | - |
| `<name>` | Required. Name of the patch envelope. |
| `--title` | Required. Display title of the patch envelope. |
| `--user-defined-version` | Required. Your own version label for the patch envelope, for example `1.0`. ZCLI does not check the format. |
| `--action` | Required. Initial state: `activate` or `store`. See [Patch Envelope States](#patch-envelope-states). |
| `--project-name` | Required. Project that the patch envelope belongs to. You can attach the patch envelope only to application instances in this project. |
| `--artifact-config-file` | Required. Path to the artifact configuration file. See [Write the Artifact Configuration File](#write-the-artifact-configuration-file). |
| `--description` | Description of the patch envelope. |

Example (create the patch envelope in the stored state, to activate it later):

```bash theme={"dark"}
zcli patch-envelope create MY_PATCH_ENVELOPE --title="Configuration update" --user-defined-version=1.0 --action=store --project-name=MY_PROJECT --artifact-config-file=./patch-artifacts.json --description="Updated settings file"
```

The artifact configuration file must be readable from inside the ZCLI container. See [Work With Local Files](https://zededa.mintlify.site/zcli-reference/get-started.md#work-with-local-files).

> [!NOTE]
>
> If you create the patch envelope with `--action=activate`, it starts delivering as soon as you attach it to application instances. Use `--action=store` if you want to attach it first and activate it later.

If the artifact configuration file is not valid JSON, ZCLI prints the parse error and `Invalid artifact config received, please input valid artifact configuration.` and does not create the patch envelope. If the file has no `artifacts` list, ZCLI prints `Unexpected error executing command 'patch-envelope'` and does not create the patch envelope. If the file does not exist, ZCLI stops with a Python error. Check the path before you run the command.

## View Patch Envelopes

### View a single patch envelope

View one patch envelope by name or by ID. Unlike most ZCLI commands, `show` takes the name as the `--name` flag, not as a positional argument.

```bash theme={"dark"}
zcli patch-envelope show [[--name=<name> | --id=<id>] [--detail] | [[[--name-pattern=<name-pattern>] [--project-name-pattern=<project-name-pattern>] [--page-size=<page-size>] [--page-num=<page-number>]] | [--summary]]]
```

| Flag | Description |
| - | - |
| `--name` | Name of the patch envelope. |
| `--id` | ID (UUID) of the patch envelope. |
| `--detail` | Show the full configuration, including every artifact. |

To view a patch envelope by name:

```bash theme={"dark"}
zcli patch-envelope show --name=MY_PATCH_ENVELOPE
```

To view the full configuration of a patch envelope:

```bash theme={"dark"}
zcli patch-envelope show --name=MY_PATCH_ENVELOPE --detail
```

To view a patch envelope by ID:

```bash theme={"dark"}
zcli patch-envelope show --id=<id>
```

Without `--detail`, the output shows the name, ID, title, user-defined version, action, project name, and creation time. The action appears as the full API value, for example `PATCH_ENVELOPE_ACTION_STORE`.

With `--detail`, the output also shows the following:

* The description and the short action value, for example `Store`.
* The project ID and project name.
* `Device Count`, the number of edge nodes the patch envelope is attached to.
* An `Inline Artifacts` table with each inline artifact's ID, metadata, file name, and base64 data.
* An `External Artifacts` table with each external artifact's ID, artifact metadata, file name, image name, image ID, and blob metadata.
* `Version`, the revision number that Edge Infrastructure Services increases each time the patch envelope changes. This is separate from the user-defined version.
* Who created and last updated the patch envelope, and when.

The inline artifacts table prints the full base64 data of each inline artifact, so the output can be long. To read the configuration as JSON, run `zcli --format=json patch-envelope show --name=MY_PATCH_ENVELOPE`.

### List patch envelopes

List all patch envelopes, or filter the list.

| Flag | Description |
| - | - |
| `--name-pattern` | Show only patch envelopes whose name contains this text. |
| `--project-name-pattern` | Show only patch envelopes whose project name contains this text. |
| `--page-size` | Number of records for each request to Edge Infrastructure Services. The default is 500. |
| `--page-num` | Page number to show, where each page holds `--page-size` records. |
| `--summary` | Show only the count of patch envelopes by action, without the list. ZCLI ignores the other filters when you pass `--summary`. |

The list shows the ID, name, title, user-defined version, action, and project name of each patch envelope, followed by a count by action.

To list all patch envelopes:

```bash theme={"dark"}
zcli patch-envelope show
```

To list the patch envelopes in projects whose name contains `MY_PROJECT`:

```bash theme={"dark"}
zcli patch-envelope show --project-name-pattern=MY_PROJECT
```

To show only the count of patch envelopes by action:

```bash theme={"dark"}
zcli patch-envelope show --summary
```

## Attach a Patch Envelope to Application Instances

ZCLI attaches and detaches patch envelopes with `zcli edge-app-instance` commands. The application instances and the patch envelope must belong to the project that you pass with `--project`.

### Attach a patch envelope

```bash theme={"dark"}
zcli edge-app-instance patch-envelope-attach --app-instance=<name>... --project=<project> --patch-envelope=<patch-envelope>
```

Repeat `--app-instance` for each application instance. The following example attaches a patch envelope to two application instances:

```bash theme={"dark"}
zcli edge-app-instance patch-envelope-attach --app-instance=MY_APP_INSTANCE_1 --app-instance=MY_APP_INSTANCE_2 --project=MY_PROJECT --patch-envelope=MY_PATCH_ENVELOPE
```

### Detach a patch envelope

```bash theme={"dark"}
zcli edge-app-instance patch-envelope-detach --app-instance=<name>... --project=<project>
```

The following example detaches the patch envelope from one application instance:

```bash theme={"dark"}
zcli edge-app-instance patch-envelope-detach --app-instance=MY_APP_INSTANCE_1 --project=MY_PROJECT
```

For details, see [Manage Patch Envelopes](https://zededa.mintlify.site/zcli-reference/applications.md#manage-patch-envelopes) in Manage Application Instances.

## Update a Patch Envelope

Change the title, description, or state of a patch envelope.

```bash theme={"dark"}
zcli patch-envelope update <name> [--title=<title>] [--description=<description>] [--action=<action>]
```

| Flag | Description |
| - | - |
| `<name>` | Required. Name of the patch envelope. |
| `--title` | New title. |
| `--description` | New description. |
| `--action` | New state: `activate` or `store`. |

### Activate a patch envelope

Set a stored patch envelope to the active state, so that it delivers its artifacts to the application instances it is attached to.

```bash theme={"dark"}
zcli patch-envelope update MY_PATCH_ENVELOPE --action=activate
```

To stop delivery without detaching the patch envelope, set it back to the stored state with `--action=store`.

> [!NOTE]
>
> `update` cannot change the artifacts, the user-defined version, or the project. To deliver different files, create a new patch envelope with a new artifact configuration file, attach it to the application instances, and then delete the old patch envelope. `update` also cannot clear the title or description. An empty value leaves the current value unchanged.

## Delete a Patch Envelope

Delete a patch envelope by name.

```bash theme={"dark"}
zcli patch-envelope delete <name>
```

Example:

```bash theme={"dark"}
zcli patch-envelope delete MY_PATCH_ENVELOPE
```

> [!WARNING]
>
> `delete` does not ask for confirmation and has no `-f` flag. ZCLI deletes the patch envelope as soon as you run the command. Edge Infrastructure Services does not delete a patch envelope that is attached to edge nodes. Detach it from all application instances first.

## Next Steps

> [card] [Manage Images](https://zededa.mintlify.site/zcli-reference/images.md)
>
> Create the patch artifact images that external artifacts reference.

> [card] [Manage Application Instances](https://zededa.mintlify.site/zcli-reference/applications.md)
>
> Attach and detach patch envelopes on application instances.

> [card] [Update Applications with Runtime Bundles](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/update-applications-with-runtime-bundles.md)
>
> Create and manage patch envelopes and binary artifacts in the Edge Infrastructure Services console.

> [card] [Overview](https://zededa.mintlify.site/zcli-reference/overview.md)
>
> All ZCLI command procedures, organized by resource type.