Create and manage Tanzu CLI contexts

This topic gives you detailed information about how to create and manage Tanzu CLI contexts on Tanzu Platform for Kubernetes.

Using tanzu login

You can use tanzu login to log in interactively (the default routine) or you can log in by using an API token.

When run, tanzu login logs you in to Tanzu Platform and creates a Tanzu CLI context associated with the organization you are logging in to. After the context is created, you can manage it using the tanzu context sub-commands.

After logging in, you can rerun tanzu login to update the authentication aspects of the existing context while keeping the rest of the context data intact.

Log in interactively

By default, Tanzu CLI uses the interactive login method. The CLI opens the browser for you to log in and attempts to log in interactively to your default Tanzu Platform cloud services organization. For more information, see the How to set your default organization section later in the topic.

You can override the default organization by setting the TANZU_CLI_CLOUD_SERVICES_ORGANIZATION_ID environment variable with the custom organization ID value. For more information about organizations in Cloud Services and how to obtain the organization ID, see the Tanzu Platform cloud services console documentation.

After successful authentication, a context of the type tanzu is created.

Example command for interactive login:

tanzu login

Note
For terminal hosts without a browser, you can set the TANZU_CLI_OAUTH_LOCAL_LISTENER_PORT environment variable with a chosen port number, and then run the tanzu login command. The CLI shows an OAuth URL link in the console and starts a local listener on the specified port. You can use SSH port-forwarding to forward the port on your machine to the terminal/server machine where the local listener is running.

After the port-forwarding is initiated, you can open the OAuth URL in your local machine browser to complete the login and create a Tanzu context.

Alternatively, you can run the tanzu login command in the terminal host. The CLI displays the OAuth URL link in the console and provides an option for you to paste the Auth code from the browser URL to the console.

Log in by using an API token

Example command to log in by using an API token:

TANZU_API_TOKEN=<APIToken> tanzu login

You can persist the environment variable in the CLI configuration file, which is used for each CLI command invocation:

tanzu config set env.TANZU_API_TOKEN <api_token>
tanzu login

Note
For cases where you want to create more than one Tanzu context for an organization, or to learn more about creating other Tanzu context types, see tanzu context create in the Tanzu CLI command reference documentation.

(Optional) Enable third-party CLI tools with tanzu contexts

If you want to use third-party CLI tools such as kubectl against a Tanzu CLI context, update your KUBECONFIG environment variable to point to the configuration file managed by the Tanzu CLI.

View the current tanzu context by running:
```
tanzu context current
```
Set your KUBECONFIG environment variable to the Kube Config value displayed in the command output.

How the use sub-commands of project, space, and clustergroup plug-ins affect the tanzu context

This section describes how using a Project, Space, or cluster group affects the current Tanzu CLI context. The following diagram shows the hierarchy of organizations, Projects, Spaces, and cluster groups:

Organization
|
 -- Projects
    |
     -- Spaces / Cluster Groups

When a Tanzu context is initially created, the context points to the organization.
When you run tanzu project use, the context that was pointing to the organization is appended to include the Project ID for the name of the Project set in the command. For example, organization/Project.
When a Project is set, and you run tanzu space use, the context that was pointing to the Project within the organization is appended to include the Space ID for the name of the Space set in the command. For example, organization/Project/Space.
When a Space is set, and you run tanzu operations clustergroup use, the Space that was set in the context is replaced by the cluster group ID for the name of the cluster group that was set in the command (organization/Project/cluster group). This is because Spaces and cluster groups are mutually exclusive siblings in the hierarchy.

When to run the tanzu project use-current command

The tanzu project use-current command enables you to remove a Space or cluster group from from your Tanzu CLI context. You might need to use this command when the Tanzu CLI context is pointing to a Space or cluster group and you want to run a CLI command against the parent Project.

To understand the hierarchical nature of organizations, Projects, and Spaces/cluster groups in the Tanzu CLI context, see the earlier How the use sub-commands of project, space, and clustergroup plug-ins affect the tanzu context section.

When to run the tanzu project unset command

The tanzu project unset command enables you to remove a Project and, if either exists, the child Space or cluster group, from your Tanzu CLI context. You might need to use this command when the Tanzu CLI context is pointing to a Project and you want to run a CLI command against the parent organization.

How to set your default organization in Tanzu Platform cloud services console

If you belong to more than one organization, you can choose which of your organizations the Tanzu CLI logs in to when you use tanzu login or tanzu context create.

In the Tanzu Platform cloud services menu, click the arrow next to your user name.
Click Set Default Organization. A list of your organizations appears.
Select the organization you want the Tanzu CLI to log in to.

How to include context information in your command prompt

Here are a few examples of how to add the current Tanzu context information to your command prompt. You can adapt these examples for your own needs.

Example of prefixing the existing main command prompt:

# bash
PS1="$(tanzu context current --short) $PS1"
# zsh
PROMPT="$(tanzu context current --short) $PROMPT"
# fish
functions --copy fish_prompt fish_prompt_ori
function fish_prompt
  echo "$(tanzu context current --short) $(fish_prompt_ori)"
end

# Example result for a main prompt that was '$ '
my-org:my-project:my-space $ _

Example of prefixing the existing main command prompt, but without showing the org-name value:

# bash
PS1="$(tanzu context current --short | cut -d: -f2-) $PS1"
# zsh
PROMPT="$(tanzu context current --short | cut -d: -f2-) $PROMPT"
# fish
functions --copy fish_prompt fish_prompt_ori
function fish_prompt
  echo "$(tanzu context current --short | cut -d: -f2-) $(fish_prompt_ori)"
end

# Example result for a main prompt that was '$ '
my-project:my-space $ _

Example of setting the reverse command prompt:

# not available for bash

# zsh
RPROMPT="<$(tanzu context current --short)>"
# fish
function fish_right_prompt
  echo "<$(tanzu context current --short)>"
end

# Example result for a main prompt that was '$ '
$ _                            <my-org:my-project:my-space>