Installing and configuring the CLI

Prerequisites

• Create an API key. See Managing API keys.
• Set the API key in a variable for subsequent steps:

  MESH_API_KEY=<your-api-key>

Downloading and installing the CLI

Downloading and installing the CLI on Ubuntu

PALMCTL_FILE_NAME=palmctl_latest_amd64.deb
curl -sSfLO https://github.com/IBM/palmctl/releases/latest/download/$PALMCTL_FILE_NAME
sudo apt install "$PWD/$PALMCTL_FILE_NAME"

Downloading and installing the CLI on RHEL

PALMCTL_FILE_NAME=palmctl_latest_x86_64.rpm
curl -sSfLO https://github.com/IBM/palmctl/releases/latest/download/$PALMCTL_FILE_NAME
sudo rpm -i "$PWD/$PALMCTL_FILE_NAME"

Downloading and installing on Mac OSX amd64

PALMCTL_FILE_NAME=palmctl_latest_macos_amd64.tar.gz
curl -sSfLO https://github.com/IBM/palmctl/releases/latest/download/$PALMCTL_FILE_NAME
tar -xvf $PALMCTL_FILE_NAME
sudo ./palmctl/install.sh
source /usr/local/etc/bash_completion.d/bash_palmctl_completion

Downloading and installing on Mac OSX arm64

PALMCTL_FILE_NAME=palmctl_latest_macos_arm64.tar.gz
curl -sSfLO https://github.com/IBM/palmctl/releases/latest/download/$PALMCTL_FILE_NAME
tar -xvf $PALMCTL_FILE_NAME
sudo ./palmctl/install.sh
source /usr/local/etc/bash_completion.d/bash_palmctl_completion

Note:

• To enable autocompletion in the zsh or fish shells, see the output of the sudo ./palmctl/install.sh command.
• If you download the palmctl package using the browser, when you run palmctl, OSX will give you the error message "palmctl" cannot be opened because the developer cannot be verified. To enable it, open System Settings, go to the Privacy & Security tab, and scroll to the Security section. You will see "palmctl" was blocked from use because it is not from an identified developer. Click Allow Anyway. (The palmctl OSX package will be notarized in a future release.)

Downloading and installing the CLI on Windows

The Windows installation script includes an optional step to install the completion feature for the Windows PowerShell console. If you use PowerShell, ensure that the PowerShell execution policy is set to a level that allows scripts to run.

You can set the execution policy by running the following command in a PowerShell console:

Set-ExecutionPolicy RemoteSigned

Complete the following steps to install the palmctl CLI:

1. Download the latest archive from palmctl CLI tool.
2. Double-click the archive file to uncompress and extract the contents.
3. Open the command prompt and navigate to the palmctl folder.
4. Run install.bat to start the installation.
5. (Optional) If you use PowerShell, enter “Y” when you are prompted Do you want to install powershell completion for palmctl[Y/N]?

Uninstalling the CLI on Windows

Complete the following steps to uninstall the CLI on Windows:

1. To uninstall palmctl, run palmctl\uninstall.bat.
2. If you installed the PowerShell completion feature, you must edit the PowerShell profile to remove the completion script. Use the following PowerShell command to edit the profile:

   notepad $PROFILE

Verifying the CLI installation

palmctl --version

Configuring the CLI

The palmctl CLI uses the following settings:

• User configuration: API key for user authentication
• Endpoint configuration: URL of Mesh
• Log configuration: Log setting management

The configuration is stored in $HOME/palmctl_config.yaml, by default. It is possible to change the CLI settings by:

• Using palmctl commands
• Exporting environment variables
• Changing the PALMCTL_CONFIG_FILE variable to point to a different configuration file
• Editing the config file directly

Changing the palmctl CLI settings using palmctl commands

Set your user API key:

palmctl config user --token $MESH_API_KEY

Set your user API key:

palmctl config user --token $MESH_API_KEY

Set the endpoint URL:

palmctl config endpoint --url https://app.hybridcloudmesh.ibm.com

(Optional) Set the TLS client certificate pair:

palmctl config endpoint --client-cert <path/to/client.crt>
palmctl config endpoint --client-key <path/to/client.key>

(Optional) Set the log file (all output will be redirected to the log file):

palmctl config logs --log-file <path/to/file.log>

Changing the CLI settings using environment variables

Any environment variable automatically overrides the corresponding value in the config file.

These variables correspond with the listed actions:

• PALMCTL_CONFIG_FILE: Change the location of the configuration file
• PALMCTL_USER_TOKEN: Set the user API key
• PALMCTL_ENDPOINT_URL: Set the Mesh URL
• PALMCTL_ENDPOINT_CA_CERT_FILE: Set the CA cert file
• PALMCTL_ENDPOINT_CLIENT_CERT_FILE: Set the client cert file
• PALMCTL_ENDPOINT_CLIENT_KEY_FILE: Set the client key file
• PALMCTL_LOG_FILE: Set a log file to use.

For example, to change the location of the CLI configuration file, set the PALMCTL_CONFIG_FILE environment variable:

export PALMCTL_CONFIG_FILE=/another/path/to/config.yaml

Editing the configuration file directly

Edit the values directly in the YAML configuration file.

Example configuration file:

user:
  token: token_string
endpoint:
  url: {{site.data.keyword.console_url}}
  cacertfile: ""
  clientcertfile: ""
  clientkeyfile: ""
logs:
  file: ""