pulsarctl Quick Reference

This quick reference covers pulsarctl syntax, describes the command operations, and provides common examples. For details about each command, including all the supported flags and subcommands, see the pulsarctl reference documentation.

For installation instructions, see Installing pulsarctl.

Syntax

Use the following syntax to run pulsarctl command from your terminal window:

pulsarctl [resource] [command] [name] [flags]

where resource, command, name, and flags are:

resource: Specifies the resource type. Resource types are case-insensitive and you can specify the singular, plural, or abbreviated forms. For example, the following commands produce the same output:
```
pulsarctl topics get mytopic
pulsarctl topic get mytopic
```
command: Specifies the operation that you want to perform one one or more resources, for example create, get, list, delete.
name: Specifies the name of the resource. Names are case-sensitive.
flags: Specifies optional flags. For example, you can use the -o or --output flags to specify the output format of a get result.

Caution

Flags that you specify from the command line override default values and any corresponding environment variables.

If you need help, run pulsarctl help from the terminal window.

Resource types (`resource`)

The following table includes a list of all the supported resource types and their descriptions.

The following table includes the descriptions for resource.

NAME	Description
bookkeeper	Operations about BookKeeper. In order to interact with the bookkeeper cluster, you need to specify `--bookie-service-url` when creating a context and make sure you are able to connect to the bookkeeper cluster via the specified service url.
broker-stats	Operations to collect broker statistics
brokers	Operations about broker(s)
clusters	Operations about Pulsar cluster(s)
topics	Operations about Pulsar topics
completion	Generates shell completion scripts
context	Interface for setting and managing Pulsar Context(s)
functions	Interface for managing Pulsar Functions (lightweight, Lambda-style compute processes that work with Pulsar)
function-worker	Operations to collect function-worker statistics
namespaces	Operations about namespaces
ns-isolation-policy	Operations about namespace isolation policy
oauth2	Operations about oauth2
package	Operations about packages
plugin	Operations about plugins
resource-quotas	Operations about resource quotas
schemas	Operations related to Schemas associated with Pulsar topics
sinks	Interface for managing Pulsar IO sinks (egress data from Pulsar)
sources	Interface for managing Pulsar IO Sources (ingress data into Pulsar)
status	Check service(broker or proxy) status
subscriptions	Operations about subscription(s)
tenants	Operations about tenant(s)
token	Operations of token
topics	Operations about topic(s)

Operations (`command`)

Specifies the operation to be performed on one or more resources. This argument is required. Common operations include create, get, delete, update, and list.

To learn more about command operations, see the pulsarctl reference documentation.

Resource Name (`name`)

Specifies the name of the resource. This argument is required.

Note

name is case-sensitive.

For example, pulsarctl topics list public/default, where pulsar/default is the namespace name.

Flags (`flags`)

Specifies the flags. This argument is optional.

For example, you can use the -s or --admin-service-url flags to specify the address and port of the admin web service URL that pulsarctl connects to.

Note

Flags that you specify from the command line override the default values and corresponding environment variables.

Tip

If you need help, run pulsarctl help from the terminal window.
For more information about pulsarctl, see [pulsarctl](link to pulsarctl website).

Output options

Use the following sections for information about how you can format the output of certain commands. For details about which commands support the various output options, see the pulsarctl reference documentation.

Formatting output

The default output format for all pulsarctl commands is the human readable plain-text format. To output details to your terminal window in a specific format, you can add either the -o or --output flags to a supported pulsarctl command.

Syntax

pulsarctl [resource] [command] [name] -o <output_format>

Depending on the pulsarctl operation, the following output formats are supported:

Output format	Description
-o json	Output a JSON formatted result.
-o yaml	Output a YAML formatted result.
-o text	Output a humand-readable result.

Enabling shell autocompletion

pulsarctl provides autocompletion support for Bash, Zsh, and Fish, which can save you a lot of typing.

Zsh

The pulsarctl completion script for Zsh can be generated with the command pulsarctl completion zsh. Sourcing the completion script in your shell enables pulsarctl autocompletion.

To configure your zsh shell, run:

mkdir -p ~/.zsh/completion/
pulsarctl completion zsh > ~/.zsh/completion/_pulsarctl

Include the directory in your $fpath, for example by adding in ~/.zshrc:

fpath=($fpath ~/.zsh/completion)
source ~/.zshrc

You may have to force rebuild zcompdump:

rm -f ~/.zcompdump; compinit

Bash

Introduction

The pulsarctl completion script for Bash can be generated with pulsarctl completion bash. Sourcing this script in your shell enables pulsarctl completion.

However, the pulsarctl completion script depends on bash-completion which you thus have to previously install.

Warning: there are two versions of bash-completion, v1 and v2. V1 is for Bash 3.2 (which is the default on macOS), and v2 is for Bash 4.1+. The pulsarctl completion script doesn’t work correctly with bash-completion v1 and Bash 3.2. It requires bash-completion v2 and Bash 4.1+. Thus, to be able to correctly use pulsarctl completion on macOS, you have to install and use Bash 4.1+ (instructions). The following instructions assume that you use Bash 4.1+ (that is, any Bash version of 4.1 or newer).

Install bash-completion

Note: As mentioned, these instructions assume you use Bash 4.1+, which means you will install bash-completion v2 (in contrast to Bash 3.2 and bash-completion v1, in which case pulsarctl completion won’t work).

You can test if you have bash-completion v2 already installed with brew list | grep bash. If not, you can install it with Homebrew:

brew install bash-completion@2

As stated in the output of this command, add the following to your ~/.bashrc file:

export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

Enable pulsarctl autocompletion

You now have to ensure that the pulsarctl completion script gets sourced in all your shell sessions. There are multiple ways to achieve this:

First, you can use bash into the bash shell.

Note: If you are using the bash shell, you can ignore it

Add the completion script to the /usr/local/etc/bash_completion.d directory:

pulsarctl completion bash >/usr/local/etc/bash_completion.d/pulsarctl.bash

Source the completion script in your ~/.bashrc file:

echo 'source /usr/local/etc/bash_completion.d/pulsarctl.bash' >> ~/.bashrc
source ~/.bashrc

You can also use a shorthand alias for pulsarctl that also works with completion:

alias p=pulsarctl
complete -o default -F \_\_start_pulsarctl p

Fish

To load completions once in your current session run:

pulsarctl completion fish | source

To load completions for each session, run:

pulsarctl completion fish > ~/.config/fish/completions/pulsarctl.fish

Syntax

Resource types (resource)

Operations (command)

Resource Name (name)

Flags (flags)

Output options

Formatting output

Syntax

Enabling shell autocompletion

Zsh

Bash

Introduction

Install bash-completion

Enable pulsarctl autocompletion

Fish

Resource types (`resource`)

Operations (`command`)

Resource Name (`name`)

Flags (`flags`)