> ## 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.

# Get Started with ZCLI

> Start ZCLI in Docker, authenticate with credentials or a session token, work with local files, and find command help and man pages.

## Introduction

ZCLI (ZEDEDA CLI) is a Docker-based command-line interface for interacting with Edge Infrastructure Services. It provides the same management capabilities as the console GUI and supports scripting and automation for routine operations.

ZCLI is one of three user agents available for Edge Infrastructure Services. The others are the console GUI and the ZEDEDA API.

## Prerequisites

* Docker Desktop installed and running.
* A ZEDEDA user account.

## Start ZCLI

ZCLI runs as a Docker container. The first time you start it, Docker pulls the required images from the ZEDEDA registry. This might take a few moments.

```text theme={"dark"}
docker run -it zededa/zcli:latest
```

## Authenticate

### Authenticate with your ZEDEDA credentials

1. Run the configure command to start the authentication prompt.

```text theme={"dark"}
zcli configure
```

2. Specify the server address. The default is `zedcontrol.zededa.net`.

3. Answer `n` when prompted with **Login with token?(y/n) \[n]:**.

4. Enter your **Username** and **Password**.

5. Specify the **Output format** for command responses, either `text` or `json`. The default is `text`.

6. Log in.

```text theme={"dark"}
zcli login
```

### Authenticate with a session token

1. Log in to the ZEDEDA console.

2. Select the **Profile avatar** in the header and select **Profile Settings**.

3. In the Session Information section, copy your session token.

4. Run the configure command.

```text theme={"dark"}
zcli configure
```

5. Specify the server address.

6. Answer `y` when prompted with **Login with token?(y/n) \[n]:**.

7. Paste the session token and press **Enter**.

8. Specify the **Output format** for command responses, either `text` or `json`. The default is `text`.

9. Log in.

```text theme={"dark"}
zcli login
```

When you run `zcli configure` again, ZCLI shows each current value in brackets. Press **Enter** to keep a value.

### Configure without prompts

To configure ZCLI in a script, pass the values as options. ZCLI prompts only for values that you do not provide.

```text theme={"dark"}
zcli configure --server=<server> --user=<username> --password='<password>' --output=<json|text>
```

To use a token instead of a username and password:

```text theme={"dark"}
zcli configure --server=<server> --token=<token> --output=<json|text>
```

| Option | Description |
| - | - |
| `-s`, `--server=<server>` | Edge Infrastructure Services server address. |
| `-u`, `--user=<userid>` | Your username. |
| `-P`, `--password=<password>` | Your password. Enclose it in single quotes if it contains special characters. |
| `-T`, `--token=<token>` | User access token. |
| `-O`, `--output=<output>` | Default output format, either `json` or `text`. |
| `-C`, `--cacerts=<cacerts>` | CA certificate bundle used to verify TLS certificates. ZCLI uses the system bundle if you omit this option. |

### Authenticate with environment variables

If ZCLI has not been configured, it can log in with credentials from environment variables instead. Set all three of the following variables when you start the container:

* `ZSERVER`: the server address.
* `ZEDUSER`: your username.
* `ZEDPASSWORD`: your password.

```text theme={"dark"}
docker run -it -e ZSERVER=<server> -e ZEDUSER=<username> -e ZEDPASSWORD='<password>' zededa/zcli:latest
```

With these variables set, ZCLI logs in automatically each time you run a command, so you do not need to run `zcli configure` or `zcli login`. ZCLI uses the environment variables only when no configuration exists. After you run `zcli configure`, ZCLI uses the saved configuration and ignores the variables.

## Log Out

To end your session, run:

```text theme={"dark"}
zcli logout
```

ZCLI ends the session and removes the session token from its configuration. Your server, username, and output format remain configured, so you can run `zcli login` to start a new session.

## Work With Local Files

Some commands read files from your computer, such as hardware model manifests, adapter network configurations, and PCR template files. ZCLI runs inside a container, so you must make those files available inside the container first. The container's working directory is `/home/zcli`.

### Mount a local directory

Start ZCLI with the `-v` option to mount a local directory into the container. The following example mounts the current directory at `/home/zcli/files`:

```text theme={"dark"}
docker run -it -v "$(pwd)":/home/zcli/files zededa/zcli:latest
```

Inside the container, refer to the files by that path, for example `files/manifest.json`. Files that ZCLI writes to the mounted directory, such as exported manifests, also appear on your computer.

### Copy a file into a running container

If ZCLI is already running, copy the file from another terminal on your computer.

1. Find the container ID.

```text theme={"dark"}
docker ps
```

2. Copy the file into the container.

```text theme={"dark"}
docker cp <file> <container-id>:/home/zcli/
```

## Available Commands

To see all available commands, run `zcli` without arguments. For a description of every command group and a link to its procedures, see [Command Index](https://zededa.mintlify.site/zcli-reference/command-index.md).

## Command Help

To see options and required parameters for a specific command, add `--help` to the command. For example, to see the options for the `datastore` command:

```text theme={"dark"}
zcli datastore --help
```

ZCLI prints the usage for every subcommand. The following is an abbreviated response:

```text theme={"dark"}
Usage:
zcli datastore create <name> [--title=<title>] --dstype=<dstype> [--description=<description>] [--fqdn=<fqdn>] [--region=<region>] [--apikey=<apikey>] [--apipass=<password>] [--dpath=<dpath>] [--origin-type=<origin-type>] [--project-scope=<project-names>]

zcli datastore show [--dstype=<dstype>] [[[<name> | --uuid=<uuid>] [--detail]] | [[--summary] | [[--name-pattern=<name-pattern>]
...
```

Reading the syntax:

* Items within angle brackets are your own specific variables, such as `<name>`.
* Items within square brackets are optional, such as `[--title=<title>]`.
* Items that contain a pipe are choices, such as between true or false in `[--clear-text=<true|false>]`.

If you type the syntax incorrectly, such as by omitting a required option, ZCLI returns an error message. For example, this command omits the required `--dstype` option:

```text theme={"dark"}
zcli datastore create MY-DS --title=MY-DS-TITLE
```

ZCLI responds:

```text theme={"dark"}
Missing required option --dstype.
```

## Man Pages

To view the manual page for a specific command, prefix the command name with `zcli-`. For example, to view the manual page for `edge-node`:

```text theme={"dark"}
man zcli-edge-node
```

Navigate man pages using:

| Key | Action |
| - | - |
| **Space** or **Page Down** | Scroll down one page. |
| **b** or **Page Up** | Scroll up one page. |
| **j** or **Down Arrow** | Scroll down one line. |
| **k** or **Up Arrow** | Scroll up one line. |
| **/** followed by text | Search forward for text. |
| **q** | Exit the man page. |

## Next Steps

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

> [card] [ZEDEDA API Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/zededa-api-overview.md)
>
> Introduction to available ZEDEDA API services and versioning.

> [card] [Edge Infrastructure Services Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/overview.md)
>
> Introduction to Edge Infrastructure Services capabilities and service areas.

> [card] [Onboard Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/onboard-nodes.md)
>
> Enroll edge nodes in Edge Infrastructure Services.