> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/streamnative/pulsarctl) under [Apache License v2.0](http://www.apache.org/licenses/LICENSE-2.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).

<Tabs>
  <Tab title="Linux">
    1. Use this command to install `pulsarctl` on the Linux operation system.

       ```bash theme={null}
       sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/streamnative/pulsarctl/master/install.sh)"
       ```

    2. Check whether `pulsarctl` is installed successfully.

       ```bash theme={null}
       pulsarctl --version
       ```
  </Tab>

  <Tab title="Mac">
    You can use the `curl` command or use Homebrew to install `pulsarctl` on a Mac.

    #### Install pulsarctl with curl command

    <span id="macos-pulsarctl-install-curl" />

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

       ```bash theme={null}
       sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/streamnative/pulsarctl/master/install.sh)"
       ```

    2. Check whether `pulsarctl` is installed successfully.

       ```bash theme={null}
       pulsarctl --version
       ```

    #### Install pulsarctl with Homebrew

    <span id="macos-pulsarctl-install-homebrew" />

    1. Add the repository.

       ```bash theme={null}
       brew tap streamnative/streamnative
       ```

    2. Install pulsarctl.

       ```bash theme={null}
       brew install pulsarctl
       ```

    3. Check whether `pulsarctl` is installed successfully.

       ```bash theme={null}
       pulsarctl --version
       ```
  </Tab>

  <Tab title="Windows">
    To install `pulsarctl` on the Windows operation system, follow these steps:

    1. Download the latest release package from [here](https://github.com/streamnative/pulsarctl/releases).

    2. Extract the pulsarctl `.tar.gz` package using Windows Explorer.

    3. Add the `pulsarctl` directory to your `PATH`.

    4. Check whether `pulsarctl` is installed successfully.

       ```bash theme={null}
       pulsarctl --version
       ```
  </Tab>
</Tabs>

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

1. [Initialize](/tools/cli/snctl/snctl-overview#configure-snctl) `snctl` configuration.
2. [Sign in](/tools/cli/snctl/snctl-overview#sign-in-to-an-organization) to an organization.
3. Use `snctl x update-pulsar-config --cluster-name` to [add a given cluster as a context](/tools/cli/snctl/snctl-overview#add-context-to-pulsarctl) to `pulsarctl`.
   ```bash theme={null}
   snctl x update-config --cluster-name <cluster-name>
   ```
4. Verify that the current context has been changed to `<cluster-name>`.
   ```bash theme={null}
   pulsarctl context current
   ```
5. 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.

<Tabs>
  <Tab title="OAuth2">
    You can use the following command to configure pulsarctl for a Pulsar cluster that is configured with OAuth2 authentication.

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="API Key">
    You can use the following commands to configure pulsarctl for a Pulsar cluster that is configured with Token authentication.

    ```bash theme={null}
    pulsarctl context set <CONTEXT_NAME> \
        --admin-service-url=<PULSAR_ADMIN_SERVICE_URL> \
        --token=<API_Key>
    ```

    or

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="mTLS">
    You can use the following commands to configure pulsarctl for a Pulsar cluster that is configured with mTLS authentication.

    ```bash theme={null}
    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.
  </Tab>
</Tabs>