Create and manage Tanzu CLI contexts

The following provides detailed information about how to create and manage Tanzu CLI contexts.

Using `tanzu login`

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

When initiated, this command logs 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 interactive login. The CLI opens the browser for you to log in and attempts to log in interactively to your default VMware Cloud Services organization (see how to set your default organization).

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 How do I manage my Cloud Services Organizations.

After successful authentication, a context of 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 using an API token

Example command to log in 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 the tanzu context create in the Tanzu CLI command reference documentation.

Enabling third-party CLI tooling with tanzu contexts

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

View the current tanzu context:
```
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` plugins affect the `tanzu` context

It’s important to understand how using a Project, Space, or cluster group affects the current Tanzu CLI context.

The following diagram describes the hierarchy of orgs, 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 which was pointing to the organization is appended to include the Project ID for name of the Project set in the command (for example, organization/Project).
When a Project has been set, and you run tanzu space use, the context which was pointing to the Project within the organization is appended to include the Space ID for name of the Space set in the command (for example, organization/Project/Space).
When a Space has been set, and you run tanzu operations clustergroup use, because Spaces and cluster groups are mutually exclusive siblings in the hierarchy, the Space which 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).

When to use `project use-current`

The information in this section will be more clear if you read the section above to understand the hierarchical nature of organizations, Projects, Spaces/cluster groups in the Tanzu CLI context.

The tanzu project use-current command enables you to remove a Space or cluster group from from your Tanzu CLI context. You may need to use this command in cases where the Tanzu CLI context is pointing to a Space or cluster group and you want to run a Tanzu CLI (or third party CLI) command against the parent Project.

When to use `project unset`

The information in this section will be more clear if you read the section above to understand the hierarchical nature of organizations, Projects, Spaces/cluster groups in the Tanzu CLI context.

The tanzu project unset command enables you to remove a Project and, if it exists, the child Space or cluster group, from your Tanzu CLI context. You may need to use this command in cases where the Tanzu CLI context is pointing to a Project and you want to run a Tanzu CLI (or third party CLI) command against the parent organization.

How to set your default organization in VMware Cloud Services portal

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

In the VMware Cloud Services menu, click the arrow next to your user name.
Click Set Default Organization.
A list of your organizations is displayed.
Select the organization you want the Tanzu CLI to log in to.

Create and manage Tanzu CLI contexts

Using tanzu login