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
```

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
```

You can use the curl command or use Homebrew to install pulsarctl on a Mac.

Install pulsarctl with curl command

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

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

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

Install pulsarctl with Homebrew

Add the repository.
```
brew tap streamnative/streamnative
```
Install pulsarctl.
```
brew install pulsarctl
```
Check whether pulsarctl is installed successfully.
```
pulsarctl --version
```

To install pulsarctl on the Windows operation system, follow these steps:

Download the latest release package from here.
Extract the pulsarctl .tar.gz package using Windows Explorer.
Add the pulsarctl directory to your PATH.
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.

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.

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

pulsarctl context set <CONTEXT_NAME> \
    --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
    --token=<API_Key>

pulsarctl context set <CONTEXT_NAME> \
    --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
    --token-file=/path/to/apikey

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.
<API_KEY>: The API Key to use.
/path/to/apikey: The file that contains the API Key.

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

pulsarctl context set <CONTEXT_NAME> \
    --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
    --tls-cert-file=/path/to/tls_cert_file \
    --tls-key-file=/path/to/tls_key_file

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.
/path/to/tls_cert_file: The TLS cert file to use.
/path/to/tls_key_file: The TLS key file to use.

On this page

Prerequisties
Operating systems
Network access
Install pulsarctl
Configure pulsarctl
Configure pulsarctl for a StreamNative Cloud cluster
Configure pulsarctl for a Pulsar cluster

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
```

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
```

You can use the curl command or use Homebrew to install pulsarctl on a Mac.

Install pulsarctl with curl command

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

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

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

Install pulsarctl with Homebrew

Add the repository.
```
brew tap streamnative/streamnative
```
Install pulsarctl.
```
brew install pulsarctl
```
Check whether pulsarctl is installed successfully.
```
pulsarctl --version
```

To install pulsarctl on the Windows operation system, follow these steps:

Download the latest release package from here.
Extract the pulsarctl .tar.gz package using Windows Explorer.
Add the pulsarctl directory to your PATH.
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.

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.

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

pulsarctl context set <CONTEXT_NAME> \
    --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
    --token=<API_Key>

pulsarctl context set <CONTEXT_NAME> \
    --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
    --token-file=/path/to/apikey

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.
<API_KEY>: The API Key to use.
/path/to/apikey: The file that contains the API Key.

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

pulsarctl context set <CONTEXT_NAME> \
    --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
    --tls-cert-file=/path/to/tls_cert_file \
    --tls-key-file=/path/to/tls_key_file

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.
/path/to/tls_cert_file: The TLS cert file to use.
/path/to/tls_key_file: The TLS key file to use.

On this page

Prerequisties
Operating systems
Network access
Install pulsarctl
Configure pulsarctl
Configure pulsarctl for a StreamNative Cloud cluster
Configure pulsarctl for a Pulsar cluster

Prerequisties

Operating systems

Network access

Install pulsarctl

Install pulsarctl with curl command

Install pulsarctl with Homebrew

Configure pulsarctl

Configure pulsarctl for a StreamNative Cloud cluster

Configure pulsarctl for a Pulsar cluster

V4.0

V3.3

V3.2

V3.1

V3.0

V2.11

V2.10

Get Started with Pulsar CLI (pulsarctl)

Prerequisties

Operating systems

Network access

Install pulsarctl

Install pulsarctl with curl command

Install pulsarctl with Homebrew

Configure pulsarctl

Configure pulsarctl for a StreamNative Cloud cluster

Configure pulsarctl for a Pulsar cluster

​Prerequisties

​Operating systems

​Network access

​Install pulsarctl

​Install pulsarctl with curl command

​Install pulsarctl with Homebrew

​Configure pulsarctl

​Configure pulsarctl for a StreamNative Cloud cluster

​Configure pulsarctl for a Pulsar cluster

V4.0

V3.3

V3.2

V3.1

V3.0

V2.11

V2.10

​Prerequisties

​Operating systems

​Network access

​Install pulsarctl

​Install pulsarctl with curl command

​Install pulsarctl with Homebrew

​Configure pulsarctl

​Configure pulsarctl for a StreamNative Cloud cluster

​Configure pulsarctl for a Pulsar cluster

Prerequisties

Operating systems

Network access

Install pulsarctl

Install pulsarctl with curl command

Install pulsarctl with Homebrew

Configure pulsarctl

Configure pulsarctl for a StreamNative Cloud cluster

Configure pulsarctl for a Pulsar cluster

Prerequisties

Operating systems

Network access

Install pulsarctl

Install pulsarctl with curl command

Install pulsarctl with Homebrew

Configure pulsarctl

Configure pulsarctl for a StreamNative Cloud cluster

Configure pulsarctl for a Pulsar cluster