diff --git a/docs/partials/replicated-cli/_authorize-with-token-note.mdx b/docs/partials/replicated-cli/_authorize-with-token-note.mdx index ca593013ba..7509b01790 100644 --- a/docs/partials/replicated-cli/_authorize-with-token-note.mdx +++ b/docs/partials/replicated-cli/_authorize-with-token-note.mdx @@ -1,3 +1,3 @@ :::note -The `replicated login` command creates a token after you log in to your vendor account in a browser and saves it to a config file. Alteratively, if you do not have access to a browser, you can set the `REPLICATED_API_TOKEN` environment variable to authenticate. For more information, see [(Optional) Set Environment Variables](/reference/replicated-cli-installing#env-var). +The `replicated login` command creates a token after you log in to your vendor account in a browser and saves it to a config file. ::: \ No newline at end of file diff --git a/docs/partials/replicated-cli/_install-docker.mdx b/docs/partials/replicated-cli/_install-docker.mdx index 5244b0b10e..64855ca3b1 100644 --- a/docs/partials/replicated-cli/_install-docker.mdx +++ b/docs/partials/replicated-cli/_install-docker.mdx @@ -2,8 +2,6 @@ For Windows users, Replicated recommends using Windows Subsystem for Linux (WSL2) and installing the Replicated using the Linux installations above. See [Linux / Windows Subsystem for Linux (WSL2)](#linux-wsl2). ::: -Installing in Docker environments requires that you set the `REPLICATED_API_TOKEN` environment variable to authorize the Replicated CLI with an API token. For more information, see [(Optional) Set Environment Variables](/reference/replicated-cli-installing#env-var). - To install and run the latest Replicated CLI in Docker environments: 1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have `Read/Write` access. See [Generating API Tokens](/vendor/replicated-api-tokens). @@ -12,25 +10,8 @@ To install and run the latest Replicated CLI in Docker environments: Download and install the files. For simplicity, the usage in the next step is represented assuming that the CLI is downloaded and installed to the desktop. -1. Authorize the Replicated CLI: - - - Through a Docker container: - - ```shell - docker run \ - -e REPLICATED_API_TOKEN=$TOKEN \ - replicated/vendor-cli --help - ``` - Replace `TOKEN` with your API token. - - - On Windows: - - ```dos - docker.exe run \ - -e REPLICATED_API_TOKEN=%TOKEN% \ - replicated/vendor-cli --help - ``` - - Replace `TOKEN` with your API token. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). - For more information about the `docker run` command, see [docker run](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation. \ No newline at end of file + :::note + Installing in Docker environments requires that you set the `REPLICATED_API_TOKEN` environment variable to authorize the Replicated CLI with an API token. For more information, see [Set Environment Variables](/reference/replicated-cli-installing#env-var). + ::: \ No newline at end of file diff --git a/docs/reference/replicated-cli-installing.mdx b/docs/reference/replicated-cli-installing.mdx index 0c1a3ed3d1..de4262d2f2 100644 --- a/docs/reference/replicated-cli-installing.mdx +++ b/docs/reference/replicated-cli-installing.mdx @@ -20,14 +20,16 @@ Complete the following prerequisites before installing the Replicated CLI: - Create a vendor account. See [Create a Vendor Account](/vendor/vendor-portal-creating-account). - To run on Linux or Mac, install [curl](https://curl.haxx.se/). - To run through a Docker container, install [docker](https://www.docker.com). +- (Recommended) For Windows users, install Linux on Windows using WSL2. See [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install). -## Install and Run +## Install You can install and run the Replicated CLI in the following environments: * Directly on MacOS * Directly on Linux -* Through Docker (Useful for Windows, GitHub Actions, or computers without sufficient access) +* On Windows Subsystem for Linux (WSL) +* Through Docker (Useful for GitHub Actions or computers without sufficient access) ### MacOS @@ -39,11 +41,7 @@ To install and run the latest Replicated CLI on MacOS: 1. -1. - - - -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). ### Linux / Windows Subsystem for Linux (WSL) {#linux-wsl2} @@ -57,33 +55,77 @@ To install and run the latest Replicated CLI on Linux or Windows Subsystem for L 1. -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). - +### Docker -1. + -### Docker / Windows +## Authenticate {#auth} - +After installing the Replicated CLI, authenticate with your Replicated credentials using one of the following methods: +* Set the `REPLICATED_API_TOKEN` environment variable to your API token +* Create a Replicated profile at `~/.replicated/config.yaml` to store your API token +* Generate a single authentication token by running `replicated login` + +The Replicated CLI determines which credentials to use for authentication in the following order: + +1. `REPLICATED_API_TOKEN` environment variable. Environment variables take precedence, allowing temporary overrides without modifying stored profiles. +2. Replicated profile passed with the `--profile` flag. This allows for a per-command override of the default Replicated profile. +3. Default Replicated profile from `~/.replicated/config.yaml` +4. Single token auth with `replicated login` + +### Add Replicated Profiles {#profiles} + +The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials. This is useful when working with multiple Replicated accounts or environments. + +Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). + +The following examples show how to add and work with Replicated profiles: + +```bash +# Add a production profile using an existing environment variable +replicated profile add prod --token='$REPLICATED_API_TOKEN' + +# Add a development profile with a direct token +replicated profile add dev --token=your-dev-token -## (Optional) Set Environment Variables {#env-var} +# List all profiles +replicated profile ls -The Replicated CLI supports setting the following environment variables: +# Switch to production profile +replicated profile use prod -* **`REPLICATED_API_TOKEN`**: A service account or user API token generated from a vendor portal team or individual account. The `REPLICATED_API_TOKEN` environment variable has the following use cases: +# Use development profile for a single command +replicated app ls --profile=dev - * To use Replicated CLI commands as part of automation (such as from continuous integration and continuous delivery pipelines), authenticate by providing the `REPLICATED_API_TOKEN` environment variable. +# Edit a profile's token +replicated profile edit dev --token=new-dev-token - * To authorize the Replicated CLI when installing and running the CLI in Docker containers. - - * Optionally set the `REPLICATED_API_TOKEN` environment variable instead of using the `replicated login` command to authorize the Replicated CLI in MacOS or Linux environments. +# Remove a profile +replicated profile rm dev -* **`REPLICATED_APP`**: The slug of the target application. +# Add profiles for different accounts +replicated profile add company-a --token=token-a +replicated profile add company-b --token=token-b - When using the Replicated CLI to manage applications through your vendor account (including channels, releases, customers, or other objects associated with an application), you can set the `REPLICATED_APP` environment variable to avoid passing the application slug with each command. +# Switch between accounts +replicated profile use company-a +replicated app ls # Lists apps for company-a -### `REPLICATED_API_TOKEN` +replicated profile use company-b +replicated app ls # Lists apps for company-b +``` + +For more information, see [replicated profile](/reference/replicated-cli-profile). + +### Set Environment Variables {#env-var} + +#### Set REPLICATED_API_TOKEN + +The `REPLICATED_API_TOKEN` environment variable can be set to a service account or user API token generated from a Vendor Portal team or individual account. + +The `REPLICATED_API_TOKEN` environment variable is required to authorize the Replicated CLI when installing and running the CLI in Docker containers. It is also helpful for running Replicated CLI commands as part of automation in CI/CD pipelines. To set the `REPLICATED_API_TOKEN` environment variable: @@ -113,13 +155,21 @@ To set the `REPLICATED_API_TOKEN` environment variable: replicated/vendor-cli --help ``` -### `REPLICATED_APP` +#### Set REPLICATED_APP + +When using the Replicated CLI to manage applications through your vendor account, you can set the `REPLICATED_APP` environment variable to the target application slug to avoid having to pass the slug with each command. To set the `REPLICATED_APP` environment variable: -1. In the [vendor portal](https://vendor.replicated.com), go to the **Application Settings** page and copy the slug for the target application. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Application_. +1. Get the application slug: + + ``` + replicated app ls + ``` + + Or, in the [Vendor Portal](https://vendor.replicated.com), go to the **Application Settings** page and copy the slug for the target application. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Application_. -1. Set the environment variable, replacing `APP_SLUG` with the slug for the target application that you retreived in the previous step: +1. Set the environment variable, replacing `APP_SLUG` with the slug that you copied in the previous step: * **MacOs or Linux**: @@ -134,6 +184,7 @@ To set the `REPLICATED_APP` environment variable: -e REPLICATED_APP=$APP_SLUG replicated/vendor-cli --help ``` + For more information about the `docker run` command, see [docker run](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation. * **Windows**: @@ -142,3 +193,15 @@ To set the `REPLICATED_APP` environment variable: -e REPLICATED_APP=%APP_SLUG% \ replicated/vendor-cli --help ``` + +### `replicated login` {#login} + +The `replicated login` command creates a token after you log in to your vendor account in a browser and saves it to a config file. + +Using the `replicated login` command requires browser access. If you do not have access to a browser, you can authenticate by adding a Replicated profile or setting the `REPLICATED_API_TOKEN` environment variable instead. See [Add Replicated Profiles](#profiles) or [Set Environment Variables](#env-var). + +To authenticate using `replicated login`: + +1. + +1. \ No newline at end of file diff --git a/docs/vendor/environment-setup.mdx b/docs/vendor/environment-setup.mdx index 27eeadd6cf..c0de6b750d 100644 --- a/docs/vendor/environment-setup.mdx +++ b/docs/vendor/environment-setup.mdx @@ -97,7 +97,7 @@ sudo mv linux-amd64/helm /usr/local/bin/helm The Replicated CLI is the primary interface for the Replicated Platform. With the Replicated CLI, you can create and manage applications, releases, channels, customers, and more. You also use the Replicated CLI to create clusters with the Compatibility Matrix. -After installing, you can authorize the Replicated CLI by logging in to your Replicated vendor account through the `replicated login` command. +After installing, authorize the Replicated CLI using your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_. For more information about installing and authorizing the Replicated CLI, see [Install the Replicated CLI](/reference/replicated-cli-installing). @@ -111,11 +111,7 @@ To install and run the latest Replicated CLI on MacOS: 1. -1. - - - -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_. #### Linux / Windows Subsystem for Linux (WSL2) {#linux-wsl2} @@ -129,11 +125,7 @@ To install and run the latest Replicated CLI on Linux or Windows Subsystem for L 1. -1. - - - -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_. #### Docker / Windows diff --git a/docs/vendor/releases-creating-cli.mdx b/docs/vendor/releases-creating-cli.mdx index 3d82ffeed9..3ca1ce0e70 100644 --- a/docs/vendor/releases-creating-cli.mdx +++ b/docs/vendor/releases-creating-cli.mdx @@ -10,9 +10,9 @@ For information about creating and managing releases with the Vendor API v3, see Before you create a release using the Replicated CLI, complete the following prerequisites: -* Install the Replicated CLI and then log in to authorize the CLI. See [Install the Replicated CLI](/reference/replicated-cli-installing). +* Install the Replicated CLI then authenticate with your Replicated credentials. See [Install the Replicated CLI](/reference/replicated-cli-installing). -* Create a new application using the `replicated app create APP_NAME` command. You only need to do this procedure one time for each application that you want to deploy. See [`app create`](/reference/replicated-cli-app-create) in _Reference_. +* If you do not yet have an application in the Replicated Platform, create a new application using the `replicated app create APP_NAME` command. See [`app create`](/reference/replicated-cli-app-create) in _Reference_. * Set the `REPLICATED_APP` environment variable to the slug of the target application. See [Set Environment Variables](/reference/replicated-cli-installing#env-var) in _Installing the Replicated CLI_. diff --git a/docs/vendor/replicated-api-tokens.md b/docs/vendor/replicated-api-tokens.md index cd44785175..62c462eb6a 100644 --- a/docs/vendor/replicated-api-tokens.md +++ b/docs/vendor/replicated-api-tokens.md @@ -4,6 +4,8 @@ import TeamTokenNote from "../partials/vendor-api/_team-token-note.mdx" This topic describes the available types of API tokens and how to generate them for use with the Replicated CLI and Replicated Vendor API v3. +The Replicated CLI also supports creating multiple authentication profiles for managing tokens across different accounts or environments. For more information, see [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_. + ## About API Tokens The Vendor API v3 is the API that manages applications in the Replicated Vendor Portal. The Replicated CLI is an implementation of the Vendor API v3. @@ -64,9 +66,11 @@ To generate a service account: 1. Copy the service account token and save it in a secure location. The token will not be available to view again. - :::note - To remove a service account, select **Remove** for the service account that you want to delete. - ::: +1. (Recommended) Add the token to a Replicated authentication profile. See [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_. + +:::note +To remove a service account, select **Remove** for the service account that you want to delete. +::: ### Generate a User API Token @@ -93,6 +97,8 @@ To generate a user API token: 1. Copy the user API token that displays and save it in a secure location. The token will not be available to view again. - :::note - To revoke a token, select **Revoke token** for the token that you want to delete. - ::: +1. (Recommended) Add the token to a Replicated authentication profile. See [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_. + +:::note +To revoke a token, select **Revoke token** for the token that you want to delete. +:::