YugabyteDB Anywhere CLI (yba)

The YugabyteDB Anywhere Command Line Interface (CLI) is an open source tool that enables you to interact with YugabyteDB Anywhere using commands from your shell. With minimal configuration, you can start running commands from the command line that implement functionality equivalent to that provided by the browser-based YugabyteDB Anywhere interface.

Reference documentation for yba CLI commands and their flags is available in the Docs folder of the GitHub repository.

The CLI can only be used with YugabyteDB Anywhere v2024.1 or later.

The CLI is {{<tags/feature/ea idea="1879">}}. Commands and options may change before {{<tags/feature/ga>}}.

Install CLI

The CLI binary is already included in your YugabyteDB Anywhere installation at the following location:

/opt/ybanywhere/software/active/yb-platform/yugaware/yba-cli

The CLI is available for the following architectures:

• Linux AMD64 and ARM64
• Darwin AMD64 and ARM64

Copy the appropriate binary to your local machine. Note that the CLI can only be used with the same or earlier version of YBA.

Need Help?

For CLI commands and options, run:

yba help

Use CLI

Using the CLI requires providing, at minimum, an API token.

You can pass the token as a flag when running CLI commands. For example:

yba universe list --apiToken "eyJ..."

For convenience, you can configure the CLI with a default API token as follows:

• Use the auth command to write the token to a CLI configuration file, as follows:

  shCopy

  yba auth
  

  At the prompt, paste your API token and press Enter.

  By default, this writes the value to the CLI configuration file $HOME/.yba-cli/.yba-cli.yaml.

  You can create multiple configuration files, and switch between them using the --config flag, or --directory flag if you want to maintain the configuration files in a directory. See Global flags for more details.

• Using environment variables. Environment variables must begin with YBA_. For example:

  shCopy

  export YBA_APITOKEN=AWERDFSSS
  yba universe list
  

If a value is set in an environment variable and a configuration file, the environment variable takes precedence. Setting the value using the flag takes precedence over both.

Environment variables

You can set the following CLI environment variables.

Syntax

yba [-h] [ <resource> ] [ <command> ] [ <flags> ]

• resource: resource to be changed
• command: command to run
• flags: one or more flags, separated by spaces.

For example:

yba universe list

Online help

Access command-line help for the CLI by running the following command:

yba help

For help with specific resource commands, use the --help or -h flag, in the following form:

yba [ resource ] [ command ] -h

For example, to print the command-line help for the cluster create command, run the following:

yba universe list -h

Print the version of the CLI:

yba --version

Global flags

The following flags can be passed in with any command. These flags can also be added to your configuration file (see Use CLI).

-a, --apiToken string : YugabyteDB Anywhere account API Key.

--config string : Configuration file (default is $HOME/.yba-cli.yaml).

--directory string : Directory containing YBA CLI configuration and generated files. If specified, the CLI looks for a configuration file named .yba-cli.yaml in this directory. Default is $HOME/.yba-cli/.

--debug : Use debug mode, same as --logLevel debug.

--disable-color : Disable colors in output. true or false (default).

-l, --logLevel string : Specify the desired level of logging. debug or info (default).

-o, --output string : Specify the desired output format. table (default), json, or pretty.

--timeout duration : Wait command timeout. For example, 5m, 1h. Default is 168h0m0s.

--wait : For long-running commands such as creating or deleting a cluster, you can use the --wait flag to display progress in the shell. true or false (default). For example:

yba universe delete \
    --name=test-universe \
    --wait

If you are using the CLI with the --wait flag in your CI system, you can set the environment variable YBA_CI to true to avoid generating unnecessary log lines.

Autocompletion

You can configure command autocompletion for your shell using the completion command. For example:

yba completion bash

This generates an autocompletion script for the specified shell. Available options are as follows:

• bash
• fish
• powershell
• zsh

Bash

yba CLI autocompletion depends on the 'bash-completion' package. If not already installed, install it using your operating system's package manager.

To load completions in your current shell session, enter the following command:

source <(yba completion bash)

To load completions for every new session, execute the following command:

#### for Linux:
yba completion bash > /etc/bash_completion.d/yba

#### for macOS:
yba completion bash > $(brew --prefix)/etc/bash_completion.d/yba

Start a new shell for the setup to take effect.

fish

To load completions in your current shell session, use the following command:

yba completion fish | source

To load completions for every new session, execute the following command:

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

Start a new shell for the setup to take effect.

PowerShell

To load completions in your current shell session, use the following command:

yba completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the preceding command to your PowerShell profile.

Zsh

If shell completion is not already enabled in your environment, you can turn it on by running the following command:

echo "autoload -U compinit; compinit" >> .zshrc

To load completions in your current shell session, enter the following command:

source <(yba completion zsh); compdef _yba yba

To load completions for every new session, execute the following:

#### for Linux:
yba completion zsh > "${fpath[1]}/_yba"

#### for macOS:
yba completion zsh > $(brew --prefix)/share/zsh/site-functions/_yba

Start a new shell for the setup to take effect.