Get Started with Pulsar CLI (pulsarctl)

The Pulsar command-line tool, pulsarctl, enables developers to administer resources in a Pulsar cluster. The tool is open-sourced under Apache License v2.0.

Prerequisties

Before moving on to the subsequent steps, ensure you review the following requirements.

Operating systems

The pulsarctl is compatible with the following operating systems and architectures only:

macOS with 64-bit Intel chips (Darwin AMD64)
macOS with Apple chips (Darwin ARM64)
Windows with 64-bit Intel or AMD chips (Microsoft Windows AMD64)
Linux with 64-bit Intel or AMD chips (Linux AMD64)
Linux with 64-bit ARM chips (Linux ARM64)

Network access

When the pulsarctl interacts with a Pulsar cluster, it requires network access to its admin service url (i.e., https://pulsar-cluster-domain-name).

Install pulsarctl

This section describes how to install pulsarctl on Linux, MAC, and Windows Operating System (OS).

Use this command to install pulsarctl on the Linux operation system.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/streamnative/pulsarctl/master/install.sh)"

Check whether pulsarctl is installed successfully.
```
pulsarctl --version
```

Configure pulsarctl

This section describes how to configure pulsarctl.

Configure pulsarctl for a StreamNative Cloud cluster

You can use snctl to configure a context for pulsarctl to be used in a StreamNative Cloud cluster.

Initialize snctl configuration.
Sign in to an organization.
Use snctl x update-pulsar-config --cluster-name to add a given cluster as a context to pulsarctl.
```
snctl x update-config --cluster-name <cluster-name>
```
Verify that the current context has been changed to <cluster-name>.
```
pulsarctl context current
```
After verifying that the cluster has been added to pulsarctl contexts, you can use pulsarctl to interact with the target cluster.

Configure pulsarctl for a Pulsar cluster

You can configure pulsarctl for a Pulsar cluster with different authentication mechanisms.

You can use the following command to configure pulsarctl for a Pulsar cluster that is configured with OAuth2 authentication.

pulsarctl context set <CONTEXT_NAME> \
    --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
    --issuer-endpoint=<OAUTH 2.0 ISSUER ENDPOINT> \
    --key-file=/path/to/credentials.json \
    --audience=<AUDIENCE>

Notes: Please replace the following variables before using the command.

<CONTEXT_NAME>: The name is used for identifying the cluster.
<PULSAR_ADMIN_SERVICE_URL>: The admin service url of the cluster to connect.
<OAUTH 2.0 ISSUER ENDPOINT>: The OAuth 2.0 issuer endpoint for the client to connect to.
/path/to/credentials.json: The private key credentials file to use.
<AUDIENCE>: The audience to use for OAuth 2.0 authentication.