Using the CLI

Prerequisites

For more information, see Installing the CLI.

Summary

The CLI carries out actions on resources, using the following command syntax:

palmctl <action> <resource> [<arguments>] [<flags>]

The CLI's context sensitive help shows a list of available commands and actions, and a summary of command usage. To view the palmctl help, use the --help or -h flag:

palmctl --help

To get help for a specific command, append it with the -–help flag. For example:

palmctl config --help

The palmctl output format is YAML by default. The yq YAML and JSON processor is a useful open source package to parse palmctl output. If you prefer the JSON format, use the -F json flag to have palmctl output JSON format. In this case, the jq JSON processor is a useful open source package to parse palmctl JSON output.

You can see more detailed output using the -v or --verbose flag to indicate the verbosity level:

• 0: Error - displays only errors. This is the default.
• 1: Warning - also displays warning messages.
• 2: Info - also displays informational messages.
• 3: Debug - also displays debug messages.
• 4: Trace - also displays low level tracing of HTTP requests.

For example:

palmctl <action> <resource> --verbose 4

palmctl actions

create

Creates the specified resource and configures it according to a YAML input file.

install

Installs software to the target environment. For example, you can install Mesh agents to a remote Kubernetes namespace, or install a single-node cluster and the corresponding Mesh agents to your local machine.

get

Get the details of one or more resources.

update

Changes the configuration of the specified resource according to a YAML input file. This is a full replacement of the resource, meaning fields that are not specified in the input file will be set to empty.

patch

Updates the specified fields in the specified resource. Fields that are not updated will retain their current value.

delete

Deletes the specified resource. This command will not show any output unless verbosity is increased using the -v <verbosity> flag.

bind

Associates related resources. Use bind to associate permissions to roles, and roles to identities.

unbind

Decouples resources previously associated with each other using the bind command.

redeploy

Redeploys a resource.

palmctl resources

Use palmctl <action> -h to see the resources that can be used with that action.

palmctl usage examples

The following commands are examples of common uses of palmctl.

In the examples that require file input, this common pattern is used:

cat << EOM | palmctl <action> <resource> <arguments> <flags> -f -
name: some-name
description: some description
EOM

In this pattern the lines following the initial command (not including the final EOM) are sent to palmctl as an input file. The details follow:

• The cat command is instructed to read input from the following lines until it reaches EOM. It is the << EOM argument that instructs it to do this.
• The cat command echoes the input it read to its output.
• The pipe command | sends the output of the cat command to the input of the palmctl command.
• The -f - flag instructs palmctl to read its input as if it was a file.

Creating an application resource

Register your application with Mesh:

cat << EOM | palmctl create application -f -
name: myapp
app_identity: app.my.domain.example
labels:                  # optional
  - app:my-app-label
EOM

Updating an application resource

Fully replace an application resource with new field values:

cat << EOM | palmctl create application -f -
name: myapp
app_identity: app.my.domain.example
labels:                  # optional
  - app:my-app-label
EOM

Updating one field in an application resource

cat << EOM | palmctl patch application --name myapp -f -
app_identity: app.my.domain.example
EOM

Get an application resource by name

palmctl get application --name myapp

Getting all application resources

palmctl get applications

Deleting an application resource by name

palmctl delete application --name myapp

Installing an Open Horizon agent

palmctl install openhorizon --name <agent_name> --namespace <agent_namespace> \
  --storage-class <storage_class> -d <install_package_location>

Assigning (binding) a role to an identity (user)

Give a user all of the permissions contained in a role:

palmctl bind identity --name <user-email> --role-name ReadAll

Removing (unbinding) a role from an identity (user)

Remove a role's permissions from a user:

palmctl unbind identity --name <user-email> --role-name ReadAll