# CLI Reference

Full command reference for the ZCP CLI.

For the interactive reference with search, see the [ZCP CLI reference on the main site](https://cloud.zcp.zsoftly.ca/).

Almost every command requires a region and project (resources and the catalog are region/project-specific). Set them once with `zcp profile add` (it captures a default region and project, like `aws configure`), or pass `--region`/`--project` / set `ZCP_REGION`/`ZCP_PROJECT`. The examples below assume a configured default. Account-level commands (`dns`, `auth`, `profile`, `region`, `project`, `cloud-provider`, `currency`, `billing-cycle`, `server`, billing/support/dashboard, and the IAM commands `sub-user`/`role`/`permission`) are exempt. See [Configuration](https://docs.zcp.zsoftly.ca/public-cloud/cli/configuration).

---

### Core

| Command | Description |
| --- | --- |
| `zcp version` | Print CLI version |
| `zcp completion <shell>` | Generate shell completions (bash\|zsh\|fish\|powershell) |
| `zcp auth validate` | Validate authentication token |

### Profile Management

| Command | Description |
| --- | --- |
| `zcp profile add` | Add a new credential profile |
| `zcp profile list` | List all profiles |
| `zcp profile show` | Show the active profile |
| `zcp profile use <name>` | Switch to a profile |
| `zcp profile update` | Update profile fields |
| `zcp profile delete <name>` | Delete a profile |
| `zcp profile rename <old> <new>` | Rename a profile |

### Compute: Instances

| Command | Description |
| --- | --- |
| `zcp instance list` | List instances |
| `zcp instance get <name>` | Get instance details |
| `zcp instance create` | Create a new instance |
| `zcp instance delete <name>` | Delete an instance |
| `zcp instance start <name>` | Start a stopped instance |
| `zcp instance stop <name>` | Power off an instance |
| `zcp instance reboot <name>` | Reboot an instance |
| `zcp instance console <name>` | Get console URL |

#### Root disk sizing

Plans are compute-only, so you choose the root disk separately when you create an instance. CLI v1.0.0 and later require `--blockstorage-plan`, `--root-disk-size`, and `--storage-category` for a new instance. The CLI no longer accepts custom CPU, memory, or disk selections. Choose a named compute plan.

```bash
zcp instance create --name my-vm \
  --template "<template-slug>" --plan "<compute-plan-slug>" \
  --blockstorage-plan "<root-storage-plan-slug>" --root-disk-size 100 \
  --network-plan "<network-plan-slug>" --storage-category "<storage-category-slug>" \
  --billing-cycle hourly
```

- `--blockstorage-plan`: the root storage tier slug. List tiers with `zcp plan storage`.
- `--root-disk-size`: the root disk size in GB for that tier.

The CLI takes slugs, not display names. List compute, storage, and network plan slugs with `zcp plan vm`, `zcp plan storage`, and `zcp plan network`. List storage categories with `zcp storage-category list`.

Changing an instance name changes its hostname. The platform can restart a running instance or start a stopped instance to apply that change.

### Compute: Kubernetes

| Command | Description |
| --- | --- |
| `zcp kubernetes list` | List clusters |
| `zcp kubernetes create` | Create a cluster |
| `zcp kubernetes start <name>` | Start a stopped cluster |
| `zcp kubernetes stop <name>` | Stop a cluster |
| `zcp kubernetes upgrade <name>` | Upgrade Kubernetes version |

#### Kubernetes Cluster Plans

CLI v1.0.0 and later require separate fixed plans for the control plane, workers, and root storage. The root storage plan and `--root-disk-size` apply to every node. Use `zcp plan kubernetes` and `zcp plan storage` to find values in the selected region.

```bash
zcp kubernetes create --name my-cluster --version "<kubernetes-version>" \
  --control-plane-plan "<control-plane-plan-slug>" \
  --worker-plan "<worker-plan-slug>" --storage-plan "<root-storage-plan-slug>" \
  --root-disk-size 100 --storage-category "<storage-category-slug>" \
  --workers 3 --ssh-key "<ssh-key-name>" --billing-cycle hourly
```

The command `zcp kubernetes scale --enable-autoscaling` submits the requested worker bounds but does not confirm that the platform added a worker. Check cluster status after the request.

### Storage: Volumes

| Command | Description |
| --- | --- |
| `zcp volume list` | List block storage volumes |
| `zcp volume create` | Create a new volume |
| `zcp volume delete <name>` | Delete a volume |

Create a volume in a named storage tier with a positive capacity in GB:

```bash
zcp volume create --name data-volume --plan "<storage-plan-slug>" --size 100 \
  --storage-category "<storage-category-slug>" --billing-cycle hourly
```

### Storage: Snapshots

| Command | Description |
| --- | --- |
| `zcp snapshot list` | List volume snapshots |
| `zcp vm-snapshot list` | List VM snapshots |

### Storage: VM Backup Schedules

`zcp vm-backup schedule` creates and manages recurring VM backup policies. Policies support hourly, daily, weekly, and monthly intervals, IANA time zones, retention counts, and paused state.

```bash
zcp vm-backup schedule create my-vm --name nightly --interval dailyAt \
  --at 01:00 --timezone America/Toronto --retention 7
zcp vm-backup schedule pause "<schedule-id>"
zcp vm-backup schedule resume "<schedule-id>"
```

Do not use `everyOtherDay`. The platform can persist the policy and then return an error. If that happens, list schedules and remove any unintended policy before retrying.

### Storage: Object Storage

| Command | Description |
| --- | --- |
| `zcp object-storage list` | List object storage instances |
| `zcp object-storage create` | Create object storage |
| `zcp object-storage delete <name>` | Delete object storage |

### Networking: VPC

| Command | Description |
| --- | --- |
| `zcp vpc list` | List VPCs |
| `zcp vpc create` | Create a VPC |
| `zcp vpc delete <name>` | Delete a VPC |

### Networking: Networks

| Command | Description |
| --- | --- |
| `zcp network list` | List networks |
| `zcp network create` | Create a network |

### Networking: Network ACLs

| Command | Description |
| --- | --- |
| `zcp acl list <vpc-slug>` | List network ACLs in a VPC |
| `zcp acl create <vpc-slug>` | Create a network ACL |
| `zcp acl delete <vpc-slug> <acl-name-or-id>` | Delete a network ACL |
| `zcp acl rules <vpc-slug> <acl-name-or-id>` | List rules in a network ACL |
| `zcp acl create-rule <vpc-slug> <acl-name-or-id>` | Add a rule to a network ACL |
| `zcp acl update-rule <vpc-slug> <acl-name-or-id> <rule-id>` | Update a network ACL rule |
| `zcp acl delete-rule <vpc-slug> <acl-name-or-id> <rule-id>` | Delete a network ACL rule |

#### Paginate ACL Rule Listings

`zcp acl rules` retrieves every API page by default. The following pagination flags are available in v0.0.31 and later:

| Flag | Description |
| --- | --- |
| `--max-items <count>` | Return at most `<count>` rules. If more rules remain, the response includes a continuation token. |
| `--starting-token <token>` | Resume a previous listing from its continuation token. |
| `--page-size <count>` | Set the number of rules requested in each API call. It does not cap the total result. |
| `--no-paginate` | Request one API page. It cannot be combined with the other pagination flags. |

Use a continuation token only with the same VPC and ACL. The token retains its page size. When you resume, omit `--page-size` or use the same value. For consistent results, resume before the ACL rules change.

With the default table output, a continuation token is written to standard error. With `-o json` or `-o yaml`, a listing that uses `--max-items`, `--starting-token`, or `--no-paginate` returns an object with `rules` and, when more rules remain, `next_token`. A default listing keeps the existing JSON array or YAML list output.

```bash
zcp acl rules my-vpc web-acl --max-items 25
zcp acl rules my-vpc web-acl --starting-token '<next-token>'
zcp acl rules my-vpc web-acl --page-size 50
zcp acl rules my-vpc web-acl --no-paginate
```

### Networking: Firewall

| Command | Description |
| --- | --- |
| `zcp firewall list` | List firewall rules |
| `zcp firewall create` | Create a firewall rule |
| `zcp firewall delete <id>` | Delete a firewall rule |

### Networking: Load Balancer

| Command | Description |
| --- | --- |
| `zcp loadbalancer list` | List load balancers |
| `zcp loadbalancer create` | Create a load balancer |

### Networking: DNS

Account-level. No `--region`/`--project` needed, except `zcp dns create` takes `--project`. See [Manage DNS with the CLI](https://docs.zcp.zsoftly.ca/public-cloud/dns/cli).

| Command | Description |
| --- | --- |
| `zcp dns list` | List DNS domains |
| `zcp dns create` | Add a domain |
| `zcp dns show <domain>` | Show a domain and its records |
| `zcp dns record-create` | Add a record by name, type, and content |
| `zcp dns record-delete` | Delete a record set by name and type |
| `zcp dns delete <domain>` | Remove a domain |

### Networking: IP Addresses

| Command | Description |
| --- | --- |
| `zcp ip list` | List public IP addresses |
| `zcp ip acquire` | Acquire a new public IP |
| `zcp ip release <id>` | Release a public IP |

### Account

| Command | Description |
| --- | --- |
| `zcp project list` | List projects |
| `zcp project create` | Create a project |
| `zcp billing list` | View billing summary |
| `zcp support list` | List support tickets |

### Identity & Access (IAM)

Account-level. No `--region`/`--project` needed. See [Roles & Permissions](https://docs.zcp.zsoftly.ca/public-cloud/iam/roles) and [Users](https://docs.zcp.zsoftly.ca/public-cloud/iam/users) for the model and the full permission catalog.

| Command | Description |
| --- | --- |
| `zcp permission list` | List the permission catalog (use `--category` to filter) |
| `zcp role list` | List roles |
| `zcp role get <slug>` | Show a role with its permissions and assigned users |
| `zcp role create` | Create a role (`--name`, repeatable `--permission <slug>`) |
| `zcp role update <slug>` | Update a role (`--permission` replaces the set) |
| `zcp role delete <slug>` | Delete a role |
| `zcp sub-user list` | List sub-users (`--role`, `--blocked` filters) |
| `zcp sub-user create` | Create a sub-user (`--name`, `--email`, `--password`, `--role`, `--project`) |
| `zcp sub-user update <id\|email>` | Update a sub-user’s name, email, role, or projects |
| `zcp sub-user block <id\|email>` | Block a sub-user (revoke access without deleting) |
| `zcp sub-user unblock <id\|email>` | Unblock a sub-user |
| `zcp sub-user delete <id\|email>` | Delete a sub-user |

For the full 200+ command listing, see the [GitHub repository](https://github.com/zsoftly/zcp-cli).