> ## 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 Jobs > Use ZCLI to create, view, and delete jobs that update EVE-OS, refresh or purge application instances, and tag nodes across a project. Use the ZEDEDA CLI (ZCLI) to manage jobs from the command line. This article covers `zcli job` commands, with syntax and examples for each operation. A job is an asynchronous bulk operation that Edge Infrastructure Services runs on many objects at once, for example on every edge node in a project. You create the job, and then check its status until it finishes. This page is the command reference. For the console view of the same jobs, see [Cloud jobs](https://zededa.mintlify.site/new-ui/infrastructure-services/monitoring-logs-events-reports-jobs.md#cloud-jobs). ## 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 a role that allows you to update the objects that the job acts on. \[TBD: confirm the minimum role required to create and delete jobs with ZCLI. Updating EVE-OS in the console requires the SysManager or SysAdmin role.] * The project, EVE-OS image, edge app, and edge nodes that you name in a job already exist. ZCLI looks each one up by name and stops with an error if it is not found. ## Job Types You choose the operation with `--job-type`. The value is case-sensitive. Each job type acts on one object type, which you pass as `--obj-type` when you view or delete the job. | Job type | What it does | Object type | Can you create it with `zcli job create`? | | - | - | - | - | | `BulkBaseosUpdate` | Updates EVE-OS (Edge Virtualization Engine) on every edge node in a project. | `edge_node` | No. See [Update EVE-OS on all nodes in a project](#update-eve-os-on-all-nodes-in-a-project). | | `BulkAppInstanceRefresh` | Refreshes every instance of an edge app in a project. | `edge_app_instance` | Yes. | | `BulkAppInstancePurge` | Refreshes and purges every instance of an edge app in a project. | `edge_app_instance` | Yes, with `--purge`. | | `BulkDeploymentTag` | Sets the deployment tag on every edge node in a project. | `edge_node` | Yes. | | `BulkDeviceTag` | Adds tags to edge nodes in a project. | `edge_node` | Yes. | | `BulkAppInstanceDeploy` | Not supported by `zcli job create`. | `edge_app_instance` | No. | | `BulkModelImport` | Imports a hardware model. ZCLI creates this job for you when you run `zcli model import`. | `edge_node` | No. | | `BulkBundleImport` | Imports an edge app. ZCLI creates this job for you when you run `zcli edge-app import`. | `edge_app` | No. | > [!NOTE] > > The `zcli job --help` text lists `BulkAppInstanceDeploy`, `BulkModelImport`, and `BulkBundleImport` as supported job types, and shows a `--model-params` form of `job create`. In the current ZCLI, `job create` with any of these job types, or with any value that is not in the preceding table, prints `ERROR Unsupported job-type.` and creates nothing. ## Create a Job `zcli job create` sends the job to Edge Infrastructure Services and returns. It does not wait for the job to finish. To follow its progress, see [View Jobs](#view-jobs). > [!WARNING] > > Jobs act on many objects at once and start immediately. There is no confirmation prompt and no dry run. Check the project name, edge app name, and node names before you run `job create`. For EVE-OS update, refresh, and purge jobs, ZCLI creates the job record first and then looks up the project and edge app. If a name is wrong, ZCLI prints an error, but the job record that it already created remains. Delete it with `zcli job delete`. See [Delete a Job](#delete-a-job). ### Update EVE-OS on all nodes in a project ```text theme={"dark"} zcli job create --job-type= --eve-image= --project= [--activate] [--retry] ``` | Flag | Description | | - | - | | `` | Name of the job. | | `--job-type` | Required. Use `BulkBaseosUpdate`. | | `--eve-image` | Required. Name of the EVE-OS image to install. | | `--project` | Required. Name of the project. The job acts on every edge node in the project. | | `--activate` | Activate the new EVE-OS image after it is installed. | | `--retry` | Retry a previous EVE-OS update. | > [!WARNING] > > In the current ZCLI, this command always fails before it sends any request. ZCLI prints `ERROR %s: %s KeyError 'retry'` followed by `Unexpected error executing command 'job'`. No job is created. Until this is fixed, update EVE-OS on each node with `zcli edge-node eveimage-update`, or update all the nodes in a project from the Edge Infrastructure Services console. See [Update EVE-OS on a Node](https://zededa.mintlify.site/zcli-reference/nodes.md#update-eve-os-on-a-node) and [Update EVE-OS on Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/update-eve-os-on-nodes.md). ### Refresh or purge application instances Refresh or purge every instance of one edge app in a project. * **Refresh** updates each application instance to the latest version of the edge app and restarts it. * **Purge** does the same and also deletes the application instance's data. ```text theme={"dark"} zcli job create --job-type= --edge-app= --project= [--purge] ``` | Flag | Description | | - | - | | `` | Name of the job. | | `--job-type` | Required. Use `BulkAppInstanceRefresh` to refresh, or `BulkAppInstancePurge` to purge. | | `--edge-app` | Required. Name of the edge app. The job acts on every instance of this edge app in the project. | | `--project` | Required. Name of the project. | | `--purge` | Purge the application instances. Required for a purge. | > [!WARNING] > > ZCLI decides between refresh and purge from `--purge`, not from `--job-type`: > > * `--job-type=BulkAppInstancePurge` without `--purge` only refreshes the application instances. > * `--job-type=BulkAppInstanceRefresh` with `--purge` purges the application instances and deletes their data. > > To purge, always pass both `--job-type=BulkAppInstancePurge` and `--purge`. To refresh, pass `--job-type=BulkAppInstanceRefresh` without `--purge`. Example: refresh every instance of `MY_EDGE_APP` in `MY_PROJECT`: ```text theme={"dark"} zcli job create MY_JOB --job-type=BulkAppInstanceRefresh --edge-app=MY_EDGE_APP --project=MY_PROJECT ``` Example: purge every instance of `MY_EDGE_APP` in `MY_PROJECT`: ```text theme={"dark"} zcli job create MY_JOB --job-type=BulkAppInstancePurge --edge-app=MY_EDGE_APP --project=MY_PROJECT --purge ``` ### Set a deployment tag on all nodes in a project ```text theme={"dark"} zcli job create --job-type= --project= --deployment-tag= ``` | Flag | Description | | - | - | | `` | Name of the job. | | `--job-type` | Required. Use `BulkDeploymentTag`. | | `--project` | Required. Name of the project. The job sets the deployment tag on every edge node in the project. | | `--deployment-tag` | Required. The deployment tag to set. | To set the deployment tag on a single node instead, use `zcli edge-node update --deployment-tag=`. See [Manage Nodes](https://zededa.mintlify.site/zcli-reference/nodes.md). Example: ```text theme={"dark"} zcli job create MY_JOB --job-type=BulkDeploymentTag --project=MY_PROJECT --deployment-tag=MY_DEPLOYMENT_TAG ``` ### Add tags to nodes in a project ```text theme={"dark"} zcli job create --job-type= --project= --device-tags=... [--device-names=... ] [--override] ``` | Flag | Description | | - | - | | `` | Name of the job. | | `--job-type` | Required. Use `BulkDeviceTag`. | | `--project` | Required. Name of the project. | | `--device-tags` | Required. Tags to add, in `key:value` format. To add more than one tag, separate them with commas in a single value, for example `--device-tags=site:north,rack:a1`. | | `--device-names` | Names of the edge nodes to tag. Separate multiple names with commas in a single value, for example `--device-names=MY_NODE_A,MY_NODE_B`. If you omit this flag, the job tags every edge node in the project. | | `--override` | Override the existing tags on the edge nodes. | > [!WARNING] > > ZCLI reads only the first `--device-tags` value and the first `--device-names` value. If you repeat either flag, ZCLI ignores the second and later values without a message. Always put all tags in one `--device-tags` value and all node names in one `--device-names` value, separated by commas. Each tag must contain exactly one colon. If a tag does not, ZCLI prints `Please provide tag values as key-value pairs. Example: region:India`, but it still creates the job and sends it with no tags. Example: tag two nodes: ```text theme={"dark"} zcli job create MY_JOB --job-type=BulkDeviceTag --project=MY_PROJECT --device-tags=site:north,rack:a1 --device-names=MY_NODE_A,MY_NODE_B ``` Example: tag every node in the project and override their existing tags: ```text theme={"dark"} zcli job create MY_JOB --job-type=BulkDeviceTag --project=MY_PROJECT --device-tags=site:north --override ``` ## View Jobs ### List jobs Run `zcli job show` without a name to list all jobs with their status, start time, and finish time. ```text theme={"dark"} zcli job show [[[ | --uuid=] --obj-type= [--detail]] | [[--name-pattern=] [--page-size=]]] ``` | Flag | Description | | - | - | | `--name-pattern` | Show only jobs whose name contains this substring. | | `--page-size` | Number of records each API call returns. This changes only how many calls ZCLI makes, not the output. | To list all jobs: ```text theme={"dark"} zcli job show ``` To list the jobs whose name contains `MY_JOB`: ```text theme={"dark"} zcli job show --name-pattern=MY_JOB ``` ### View a single job Show one job by name or UUID. `--obj-type` is required and must match the job type. See [Job Types](#job-types). | Flag | Description | | - | - | | `--obj-type` | Required. The object type of the job: `edge_node`, `edge_app_instance`, `edge_app`, or `deployment`. ZCLI does not check the value. It looks up the job under the object type that you pass, so a job created as one object type is not found under another. | | `--uuid` | Show the job with this UUID instead of by name. | | `--detail` | Include the selection criteria, error details, success and failure counts, and creation and modification history. | Example: ```text theme={"dark"} zcli job show MY_JOB --obj-type=edge_app_instance --detail ``` The output includes the following fields: | Field | Description | | - | - | | `Job Criteria` | The number of objects that have reported a result. With `--detail`, EVE-OS update jobs also show the project, and refresh and purge jobs also show the project and an `app` field. The `app` field can be empty, because ZCLI reads the edge app from a different field than the one it sends when it creates the job. | | `Status` | The job status, for example `Completed`, `Failed`, or `Aborted`. | | `Details` | Error details for the job, if any. Shown with `--detail`. | | `Bulk Operation Type` | The operation the job runs. | | `Start Time` and `Finish Time` | When the job started and finished. | | `Total Edge Object Successful Operations` and `Total Edge Object Failed Operations` | How many objects succeeded and failed. Shown with `--detail`. | > [!NOTE] > > ZCLI fills in `Start Time` and `Finish Time` only after a job has a finish time. While a job is still running, both fields are empty, in the list and in the single-job view. ## Delete a Job Delete a job record by name. `--obj-type` is required and must match the job type. ZCLI asks `Delete job ? [Y/N]` unless you pass `-f`. If you answer no, ZCLI prints `job not deleted`. ```text theme={"dark"} zcli job delete --obj-type= [-f] ``` Example: ```text theme={"dark"} zcli job delete MY_JOB --obj-type=edge_app_instance -f ``` > [!NOTE] > > The `zcli job --help` example deletes an EVE-OS update job with `--obj-type=edge_app`. EVE-OS update jobs use `edge_node`. Use the object type from [Job Types](#job-types). ## Jobs Created by Other Commands Some ZCLI commands create a job for you: * `zcli model import` creates a `BulkModelImport` job with a random UUID as its name, and waits until the job finishes. If the job fails or is aborted, ZCLI prints `import failed (job=)`. To look up the job, use `--obj-type=edge_node`. See [Manage Hardware Models](https://zededa.mintlify.site/zcli-reference/hardware-models.md). * `zcli edge-app import` creates a `BulkBundleImport` job with a random UUID as its name, and waits until the job finishes. If the job fails or is aborted, ZCLI prints `import failed (job=)`. To look up the job, use `--obj-type=edge_app`. * `zcli project create` for a deployment project and `zcli project update-deployment` return immediately and print a message that ends with `track job to know the status`. \[TBD: confirm the `--obj-type` to use with `zcli job show --uuid=` for deployment jobs. The help text lists `deployment`.] See [Manage Projects](https://zededa.mintlify.site/zcli-reference/projects.md). ## Next Steps > [card] [Manage Nodes](https://zededa.mintlify.site/zcli-reference/nodes.md) > > Update EVE-OS, set tags, and manage individual edge nodes. > [card] [Manage Application Instances](https://zededa.mintlify.site/zcli-reference/applications.md) > > Refresh, purge, and manage individual application instances. > [card] [View Events](https://zededa.mintlify.site/zcli-reference/events.md) > > Review events from your edge nodes and user actions. > [card] [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md) > > Install ZCLI, configure access to Edge Infrastructure Services, and sign in.