# PCD CLI - pcdctl

<code class="expression">space.vars.product\_acronym</code> CLI (`pcdctl`) is a unified command line interface (CLI) tool to manage all your <code class="expression">space.vars.product\_name</code> services. `pcdctl` lets you install, manage, update Platform9 host agent and related software components on your hypervisor hosts. It also enables you to run all supported operations across all <code class="expression">space.vars.product\_name</code> services. The goal of <code class="expression">space.vars.product\_acronym</code> CLI is to be a single unified tool that enables you to control all <code class="expression">space.vars.product\_name</code> services and automate them.

## Under The Hood

`pcdctl` acts as a wrapper on [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) and exposes all OpenStack CLI commands for OpenStack services that <code class="expression">space.vars.product\_name</code> is API compatible with. Read [Service Specific Commands](#service-specific-commands) for more info.

`pcdctl` also provides access to all non OpenStack services that <code class="expression">space.vars.product\_name</code> utilizes and exposes.

{% hint style="warning" %}
**Important**

`pcdctl` acts as a wrapper on [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) and exposes all OpenStack CLI commands for OpenStack services that <code class="expression">space.vars.product\_name</code> is API compatible with. Read [Service Specific Commands](#service-specific-commands) for more info.
{% endhint %}

## Before You Install

Before you install <code class="expression">space.vars.product\_acronym</code> CLI, please note the following:

* If you have <code class="expression">space.vars.product\_acronym</code> CLI installed previously and need to update it with the latest <code class="expression">space.vars.product\_acronym</code> CLI then do run the command`rm /usr/bin/pcdctl` before running the curl to the setup script
* When using <code class="expression">space.vars.product\_acronym</code> CLI to prepare and onboard a new host to be added to <code class="expression">space.vars.product\_name</code>, you need to install and run the CLI on the host being added. Ability to perform remote install and onboarding of new host using <code class="expression">space.vars.product\_acronym</code> is coming in the future.
* When using <code class="expression">space.vars.product\_acronym</code> CLI to control your <code class="expression">space.vars.product\_name</code> services, you can run <code class="expression">space.vars.product\_acronym</code> CLI on any node with network connectivity to your <code class="expression">space.vars.product\_name</code> environment.

## Prerequisites

* If using <code class="expression">space.vars.product\_acronym</code> CLI to onboard a new host into your <code class="expression">space.vars.product\_name</code> setup, make sure to install <code class="expression">space.vars.product\_acronym</code> CLI on that host. Also ensure that the [host prerequisites](https://docs.platform9.com/private-cloud-director/2025.10/getting-started/pre-requisites#hypervisor-host-prerequisites) are met before using <code class="expression">space.vars.product\_acronym</code> CLI to onboard a new host.
* If using <code class="expression">space.vars.product\_acronym</code> to access your <code class="expression">space.vars.product\_name</code> service specific commands beyond host onboarding, you can install it on any Ubuntu machine with network access to your <code class="expression">space.vars.product\_name</code> setup.
* If your host is configured with network bonds, verify that the bonding mode is either active-passive or LACP.

## Installation

To install <code class="expression">space.vars.product\_acronym</code> CLI `pcdctl`, execute the following command on the machine you are installing the CLI on:

{% tabs %}
{% tab title="Bash" %}

```yaml
bash <(curl -s https://pcdctl.s3.us-west-2.amazonaws.com/pcdctl-setup)
```

{% endtab %}
{% endtabs %}

To view available commands and their information, use the help command:

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl --help
```

{% endtab %}
{% endtabs %}

For help with a specific command, run the following:

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl [command] --help
```

{% endtab %}
{% endtabs %}

### Global Flags

Following global flags apply to any run of `pcdctl`

`--log-dir` string — path to save pcdctl logs

`--no-prompt` disable all user prompts

`--verbose` print verbose logs

## Configuration

Before using `pcdctl` with your <code class="expression">space.vars.product\_name</code> environment, you need to configure it:

1. Navigate to `Settings` menu option located on the top right corner in the UI.
2. Choose API Access -> pcdctl RC.
3. Copy the contents to a new file named `pcdctlrc`
4. Update `OS_PASSWORD` with your <code class="expression">space.vars.product\_name</code> password
5. Run `source pcdctlrc` to set the required environment variables

### Configuration Commands

#### config set

This command sets the configuration details for your <code class="expression">space.vars.product\_name</code> setup. These configuration details are stored in ``~/pf9/db/config.json `file`.``

Run this command first prior to running any other `pcdctl` commands to set your account url and credentials once instead of having to specify it for each command.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl config set
```

{% endtab %}
{% endtabs %}

**Parameters**:

`-u, --account-url` string – Sets account URL

`-h, --help` – Displays help for set

`-p, --password` string – Sets password (use 'single quotes' to pass password)

`-r, --region` string – Sets region

`-t, --tenant` string – Sets tenant

`-e, --username` string – Sets the username

`-l, --proxy-url` string — Sets the http(s) proxy URL specified as \[]\[:@]:

{% hint style="warning" %}
For the repository specified by the `--private-package-repo` flag to be used to install dependencies and to avoid configuring ubuntu official repositories `pcdctl prep-node` must be run with the `--skip-repo-config` flag.

**Note:** User themselves needs to make sure no unreachable apt sources are present before they run pcdctl. Also, users need to manually trust CA certs for Self-Signed Private Registries as this is NOT being handled within pcdctl.
{% endhint %}

`--private-package-repo` string — Sets the URL for the registry to use for installing dependencies

#### config get

Retrieves the current configuration settings

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl config get
```

{% endtab %}
{% endtabs %}

## Host Onboarding & Management Commands

### prep-node

The `prep-node` command allows you to add a new host to your <code class="expression">space.vars.product\_name</code> environment. This command prepares the host with required pre-requisites by downloading and installing a set of required software packages on the host, so that it can be used in your <code class="expression">space.vars.product\_name</code> environment.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl prep-node
```

{% endtab %}
{% endtabs %}

**Parameters:**

{% hint style="info" %}
You can configure the private repository by using  `pcdctl config set --private-package-repo <repo>`&#x20;
{% endhint %}

`--skip-repo-config` boolean, default: false — disable configuration of ubuntu cloud archive repos - only applicable if using private repos to host dependencies

### authorize-node

This command assigns a <code class="expression">space.vars.product\_name</code> role to the host.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl authorize-node [flags]
```

{% endtab %}
{% endtabs %}

Flags:

`-h, --help` help message for authorize-node

`--role` string role for the host

### decommission-node

Decommissions this host from <code class="expression">space.vars.product\_acronym</code> management plane and purges all <code class="expression">space.vars.product\_acronym</code> components on the host.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl decommission-node [flags]
```

{% endtab %}
{% endtabs %}

**Parameters**:

`-h, --help` help message for decommission-node

`-f, --force` force decommission node purging everything

`-r, --skip-installed-role-check` — skip checking for installed roles

### deauthorize-node

Removes roles from an onboarded node.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl deauthorize-node [flags]
```

{% endtab %}
{% endtabs %}

**Parameters**:

`-h, --help` help message for deauthorize-node

`-t, --timeout` string, default: "5m", timeout for the operation

## Service Specific Commands

`pcdctl` acts as a wrapper on open source [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) for all operations specific to the following <code class="expression">space.vars.product\_name</code> services, as these services expose OpenStack APIs.

* Compute Service
* Block Storage Service
* Network Service
* Identity Service

It exposes all commands that are exposed by the [OpenStack CLI](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) corresponding to these services.

You can find a [complete reference here](https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html) for supported OpenStack CLI commands. When executing these commands with pcdctl, replace `openstack` with `pcdctl` before executing the command.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl [command] [flags] [subcommands]
```

{% endtab %}
{% endtabs %}

**Examples**

Following command lists all block storage volumes.

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl volume list
```

{% endtab %}
{% endtabs %}

Following command lists all networks in your <code class="expression">space.vars.product\_name</code> setup

{% tabs %}
{% tab title="Bash" %}

```yaml
pcdctl network list
```

{% endtab %}
{% endtabs %}

## Troubleshooting

If you encounter issues:

* Ensure your configuration file is sourced correctly
* If you receive endpoint or SSLErrors, it is likely due to using a self-signed certificate. The `--insecure` flag can be used as a workaround
* Verify network connectivity to your <code class="expression">space.vars.product\_name</code> environment
* Check that you have the necessary permissions for the operation
* Review logs for detailed error information

#### Support bundle

The `pcdctl generate-support-bundle` utility generates an encrypted archive file containing logs and configuration files specific to PCD troubleshooting scenarios. This command must be **executed from the host** where the support bundle is required, as the collected data pertains exclusively to that host.

Options specific to the `generate-support-bundle` command are:

{% tabs %}
{% tab title="Bash" %}

```yaml
$ sudo pcdctl generate-support-bundle --help
Gathers support bundle that includes logs for pf9 services and pf9ctl.

Usage:
  pcdctl generate-support-bundle [flags]

Flags:
  -h, --help   help for generate-support-bundle

Global Flags:
      --log-dir string   path to save logs
      --no-prompt        disable all user prompts
      --verbose          print verbose logs
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Info**

It is recommended to run the command with `--verbose` option to monitor the progress of support bundle generation.
{% endhint %}

The command to generate the support bundle is:

{% tabs %}
{% tab title="Bash" %}

```ruby
$ sudo pcdctl generate-support-bundle --verbose
```

{% endtab %}
{% endtabs %}

A sample execution of the support bundle generation:

{% tabs %}
{% tab title="Bash" %}

```ruby
$ sudo pcdctl generate-support-bundle --verbose

DEBUG ==========Genetating SupportBundle==========
DEBUG Using local executor
Generating support bundle...
DEBUG Ran command sudo "bash" "-c" "LD_LIBRARY_PATH="/opt/pf9/python/pf9-lib:${LD_LIBRARY_PATH}""
DEBUG stdout:stderr:
DEBUG Ran command sudo "bash" "-c" "PYTHONPATH="/opt/pf9/python/lib/python3.9:${PYTHONPATH}""
DEBUG stdout:stderr:
Generating support bundle...
DEBUG Ran command sudo "bash" "-c" "/opt/pf9/hostagent/bin/python /opt/pf9/hostagent/lib/python3.9/site-packages/datagatherer/datagatherer.py"
DEBUG stdout:stderr:
Generating support bundle...
DEBUG Ran command sudo "bash" "-c" "ls /tmp | grep -i pf9-support.tgz.*"
DEBUG stdout:pf9-support.tgz.[hash].gpg
stderr:
✓ Support bundle generated successfully. 
✓ Location of bundle: /tmp/pf9-support.tgz.*.gpg
```

{% endtab %}
{% endtabs %}

The archived contents are stored in an encrypted format within the *`/tmp/pf9-support.tgz.*.gpg`* file by default. For comprehensive guidance on sharing the support bundle, please reach out to the Platform9 support team.

To specify a custom path for the archived support bundle, use the `--log-dir` option.

{% tabs %}
{% tab title="Bash" %}

```ruby
$ sudo pcdctl generate-support-bundle --log-dir <PATH_TO_FOLDER> --verbose
```

{% endtab %}
{% endtabs %}