From f5964040d7c420220bed2625796f0c264a971d52 Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Tue, 30 Apr 2024 15:47:24 -0700 Subject: [PATCH] Update CLI usage page --- docs/cli/commands/secrets.mdx | 2 +- docs/cli/commands/service-token.mdx | 33 ++- docs/cli/usage.mdx | 354 +++++++++++++++------------- 3 files changed, 207 insertions(+), 182 deletions(-) diff --git a/docs/cli/commands/secrets.mdx b/docs/cli/commands/secrets.mdx index bc6e8a3f52..6615a6d57f 100644 --- a/docs/cli/commands/secrets.mdx +++ b/docs/cli/commands/secrets.mdx @@ -206,7 +206,7 @@ $ infisical secrets folders - Fetch folders using an [machine identity](/documentation/platform/identities/machine-identities) access token. + Fetch folders using a [machine identity](/documentation/platform/identities/machine-identities) access token. Default value: `` diff --git a/docs/cli/commands/service-token.mdx b/docs/cli/commands/service-token.mdx index 1097c08f66..4971b3db04 100644 --- a/docs/cli/commands/service-token.mdx +++ b/docs/cli/commands/service-token.mdx @@ -4,40 +4,46 @@ description: "Manage Infisical service tokens" --- - This command is deprecated and will be removed in the near future. Please switch to [Machine Identities](/documentation/platform/identities/machine-identities) for authenticating with Infisical. + This command is deprecated and will be removed in the near future. Please + switch to using [Machine + Identities](/documentation/platform/identities/machine-identities) for + authenticating with Infisical. -```bash +```bash infisical service-token create --scope=dev:/global --scope=dev:/backend --access-level=read --access-level=write ``` ## Description -The Infisical `service-token` command allows you to manage service tokens for a given Infisical project. + +The Infisical `service-token` command allows you to manage service tokens for a given Infisical project. With this command, you can create, view, and delete service tokens. Use this command to create a service token - ```bash - $ infisical service-token create --scope=dev:/backend/** --access-level=read --access-level=write - ``` +```bash +$ infisical service-token create --scope=dev:/backend/** --access-level=read --access-level=write +``` + +### Flags - ### Flags ```bash infisical service-token create --scope=dev:/global --scope=dev:/backend/** --access-level=read ``` Use the scope flag to define which environments and paths your service token should be authorized to access. - - The value of your scope flag should be in the following `:`. + + The value of your scope flag should be in the following `:`. Here, `environment slug` refers to the slug name of the environment, and `path` indicates the folder path where your secrets are stored. For specifying multiple scopes, you can use multiple --scope flags. - + The `path` can be a Glob pattern + @@ -45,8 +51,9 @@ With this command, you can create, view, and delete service tokens. infisical service-token create --scope=dev:/global --access-level=read --projectId=63cefb15c8d3175601cfa989 ``` - The project ID you'd like to create the service token for. + The project ID you'd like to create the service token for. By default, the CLI will attempt to use the linked Infisical project in `.infisical.json` generated by `infisical init` command. + ```bash @@ -56,6 +63,7 @@ With this command, you can create, view, and delete service tokens. Service token name Default: `Service token generated via CLI` + ```bash @@ -65,6 +73,7 @@ With this command, you can create, view, and delete service tokens. Set the service token's expiration time in seconds from now. To never expire set to zero. Default: `1 day` + ```bash @@ -72,6 +81,7 @@ With this command, you can create, view, and delete service tokens. ``` The type of access the service token should have. Can be `read` and or `write` + ```bash @@ -81,5 +91,6 @@ With this command, you can create, view, and delete service tokens. When true, only the service token will be printed Default: `false` + diff --git a/docs/cli/usage.mdx b/docs/cli/usage.mdx index 9ee9fede4b..b7abdbe480 100644 --- a/docs/cli/usage.mdx +++ b/docs/cli/usage.mdx @@ -1,182 +1,125 @@ --- -title: "Quick usage" +title: "Quickstart" description: "Manage secrets with Infisical CLI" --- -The CLI is designed for a variety of applications, ranging from local secret management to CI/CD and production scenarios. -The distinguishing factor, however, is the authentication method used. +The CLI is designed for a variety of secret management applications ranging from local development to CI/CD and production scenarios. - - To use the Infisical CLI in your local development environment, simply run the command below and follow the interactive guide. + + In the following steps, we explore how to use the Infisical CLI to fetch back environment variables from Infisical + and inject them into your local development process. + + + + Start by running the `infisical login` command to authenticate with Infisical. + + ```bash + infisical login + ``` + + If you are in a containerized environment such as WSL 2 or Codespaces, run `infisical login -i` to avoid browser based login + + + + Next, navigate to your project and initialize Infisical. + + ```bash + # navigate to your project + cd /path/to/project - ```bash - infisical login - ``` + # initialize infisical + infisical init + ``` - - If you are in a containerized environment such as WSL 2 or Codespaces, run `infisical login -i` to avoid browser based login - + The `infisical init` command creates a `.infisical.json` file, containing [local project settings](./project-config), at the location where the command is executed. - ## Initialize Infisical for your project + + The `.infisical.json` file does not contain any sensitive data, so you may commit it to your git repository. + + + + Finally, pass environment variables from Infisical into your application. - ```bash - # navigate to your project - cd /path/to/project + + + ```bash + infisical run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev - # initialize infisical - infisical init - ``` + # example with node (nodemon) + infisical run --env=staging --path=/apps/spotify -- nodemon index.js + + # example with flask + infisical run --env=prod --path=/apps/backend -- flask run + + # example with spring boot - maven + infisical run --env=dev --path=/apps/ -- ./mvnw spring-boot:run --quiet + ``` + + + + Custom aliases can utilize secrets from Infisical. Suppose there is a custom alias `yd` in `custom.sh` that runs `yarn dev` and needs the secrets provided by Infisical. + ```bash + #!/bin/sh + + yd() { + yarn dev + } + ``` + + To make the secrets available from Infisical to `yd`, you can run the following command: + + ```bash + infisical run --env=prod --path=/apps/reddit --command="source custom.sh && yd" + ``` + + + + View all available options for `run` command [here](./commands/run) + + - This will create `.infisical.json` file at the location the command was executed. This file contains your [local project settings](./project-config). It does not contain any sensitive data. - - - - - - ## Machine Identities - - To use Infisical for non local development scenarios, please create a [machine identity](../documentation/platform/identities/machine-identities). The machine identity will allow you to authenticate and interact with Infisical. - Once you have created a machine identity with the required permissions, you'll need to feed the token to the CLI. - - #### Use `infisical login` to obtain a universal auth access token - + + In the following steps, we explore how to use the Infisical CLI in a non-local development scenario + to fetch back environment variables and export them to a file. + + + Follow the steps listed [here](/documentation/platform/identities/universal-auth) to create a machine identity and obtain a **client ID** and **client secret** for it. + + + Run the following command to authenticate with Infisical using the **client ID** and **client secret** credentials from step 1 and set the `INFISICAL_TOKEN` environment variable to the retrieved access token. + ```bash export INFISICAL_TOKEN=$(infisical login --method=universal-auth --client-id= --client-secret= --silent --plain) # --plain flag will output only the token, so it can be fed to an environment variable. --silent will disable any update messages. ``` - The CLI is configured to look for the `INFISICAL_TOKEN` environment variable. You can also pass the universal auth token as a `--token` flag to commands. + The CLI is configured to look out for the `INFISICAL_TOKEN` environment variable, so going forward any command used will be authenticated. + + Alternatively, assuming you have an access token on hand, you can also pass it directly to the CLI using the `--token` flag in conjunction with other CLI commands. - Keep in mind that the universal auth token has a limited lifetime. It is recommended to use it only for the duration of the task at hand. + Keep in mind that the machine identity access token has a limited lifetime. It is recommended to use it only for the duration of the task at hand. You can [refresh the token](./commands/token) if needed. - - - #### Run commands with the universal auth token - - When using universal auth it's required to pass the `--projectId` flag. + + + + Finally, export the environment variables from Infisical to a file of choice. ```bash - # Use the token for your commands. - infisical export --projectId= - infisical secrets --projectId= - infisical run --projectId= -- npm run dev + # export variables to a .env file (with export keyword) + infisical export --format=dotenv-export > .env + + # export variables to a YAML file + infisical export --format=yaml > secrets.yaml ``` - - + + - ## Service Tokens - - - Service tokens are deprecated and will be removed in the near future. Please switch to [Machine Identities](../documentation/platform/identities/machine-identities) for authenticating with Infisical. - - - To use Infisical for non local development scenarios, please create a service token. The service token will allow you to authenticate and interact with Infisical. Once you have created a service token with the required permissions, you’ll need to feed the token to the CLI. - - ```bash - infisical export --token= - infisical secrets --token= - infisical run --token= -- npm run dev - ``` - - - #### Pass via shell environment variable - The CLI is configured to look for an environment variable named `INFISICAL_TOKEN`. If set, it’ll attempt to use it for authentication. - - ```bash - export INFISICAL_TOKEN= - ``` - - - - - - - -## Inject environment variables - - - ```bash - infisical run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev - - # example with node (nodemon) - infisical run --env=staging --path=/apps/spotify -- nodemon index.js - - # example with flask - infisical run --env=prod --path=/apps/backend -- flask run - - # example with spring boot - maven - infisical run --env=dev --path=/apps/ -- ./mvnw spring-boot:run --quiet - ``` - - - Custom aliases can utilize secrets from Infisical. Suppose there is a custom alias `yd` in `custom.sh` that runs `yarn dev` and needs the secrets provided by Infisical. - ```bash - #!/bin/sh - - yd() { - yarn dev - } - ``` - - To make the secrets available from Infisical to `yd`, you can run the following command: - - ```bash - infisical run --env=prod --path=/apps/reddit --command="source custom.sh && yd" - ``` - - - -View all available options for `run` command [here](./commands/run) - -## Connect CLI to self hosted Infisical - - -The CLI is set to connect to Infisical Cloud by default, but if you're running your own instance of Infisical, you can direct the CLI to it using one of the methods provided below. - -#### Method 1: Use the updated CLI -Beginning with CLI version V0.4.0, it is now possible to choose between logging in through the Infisical cloud or your own self-hosted instance. Simply execute the `infisical login` command and follow the on-screen instructions. - -#### Method 2: Export environment variable -You can point the CLI to the self hosted Infisical instance by exporting the environment variable `INFISICAL_API_URL` in your terminal. - - - - ```bash - # Set backend host - export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api" - - # Remove backend host - unset INFISICAL_API_URL - ``` - - - ```bash - # Set backend host - setx INFISICAL_API_URL "https://your-self-hosted-infisical.com/api" - - # Remove backend host - setx INFISICAL_API_URL "" - - # NOTE: Once set or removed, please restart powershell for the change to take effect - ``` - - - -#### Method 3: Set manually on every command -Another option to point the CLI to your self hosted Infisical instance is to set it via a flag on every command you run. - -```bash -# Example -infisical --domain="https://your-self-hosted-infisical.com/api" -``` - - ## History Your terminal keeps a history with the commands you run. When you create Infisical secrets directly from your terminal, they'll stay there for a while. @@ -184,30 +127,101 @@ Your terminal keeps a history with the commands you run. When you create Infisic For security and privacy concerns, we recommend you to configure your terminal to ignore those specific Infisical commands. + + + + `$HOME/.profile` is pretty common but, you could place it under `$HOME/.profile.d/infisical.sh` or any profile file run at login + - - - - `$HOME/.profile` is pretty common but, you could place it under `$HOME/.profile.d/infisical.sh` or any profile file run at login - + ```bash + cat <> $HOME/.profile && source $HOME/.profile + # Ignoring specific Infisical CLI commands + DEFAULT_HISTIGNORE=$HISTIGNORE + export HISTIGNORE="*infisical secrets set*:$DEFAULT_HISTIGNORE" + EOF + ``` + + + + If you're on WSL, then you can use the Unix/Linux method. + + + Here's some [documentation](https://superuser.com/a/1658331) about how to clear the terminal history, in PowerShell and CMD + + + + + + + +## FAQ + + + + Yes. The CLI is set to connect to Infisical Cloud by default, but if you're running your own instance of Infisical, you can direct the CLI to it using one of the methods provided below. + + #### Method 1: Use the updated CLI + + Beginning with CLI version V0.4.0, it is now possible to choose between logging in through the Infisical cloud or your own self-hosted instance. Simply execute the `infisical login` command and follow the on-screen instructions. + + #### Method 2: Export environment variable + + You can point the CLI to the self hosted Infisical instance by exporting the environment variable `INFISICAL_API_URL` in your terminal. + + + ```bash - cat <> $HOME/.profile && source $HOME/.profile + # set backend host + export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api" - # Ignoring specific Infisical CLI commands - DEFAULT_HISTIGNORE=$HISTIGNORE - export HISTIGNORE="*infisical secrets set*:$DEFAULT_HISTIGNORE" - EOF + # remove backend host + unset INFISICAL_API_URL ``` - - - If you're on WSL, then you can use the Unix/Linux method. + + + ```bash + # set backend host + setx INFISICAL_API_URL "https://your-self-hosted-infisical.com/api" - - Here's some [documentation](https://superuser.com/a/1658331) about how to clear the terminal history, in PowerShell and CMD - + # remove backend host + setx INFISICAL_API_URL "" - - - \ No newline at end of file + # NOTE: Once set or removed, please restart powershell for the change to take effect + ``` + + + + + +#### Method 3: Set manually on every command + +Another option to point the CLI to your self hosted Infisical instance is to set it via a flag on every command you run. + +```bash +# Example +infisical --domain="https://your-self-hosted-infisical.com/api" +``` + + + + Yes. Please note, however, that service tokens are being deprecated. They will be removed in the future in accordance with the deprecation notice and timeline stated [here](https://infisical.com/blog/deprecating-api-keys). + + To use Infisical for non local development scenarios, please create a service token. The service token will allow you to authenticate and interact with Infisical. Once you have created a service token with the required permissions, you’ll need to feed the token to the CLI. + + ```bash + infisical export --token= + infisical secrets --token= + infisical run --token= -- npm run dev + ``` + + #### Pass via shell environment variable + The CLI is configured to look for an environment variable named `INFISICAL_TOKEN`. If set, it’ll attempt to use it for authentication. + + ```bash + export INFISICAL_TOKEN= + ``` + + +