diff --git a/docs/@v1/installation.md b/docs/@v1/installation.md index 63fbb66a89..6c00c5dd53 100644 --- a/docs/@v1/installation.md +++ b/docs/@v1/installation.md @@ -2,92 +2,120 @@ Choose the most appropriate installation method for your needs: -- [Install locally, using `npm`](#install-globally) to make the `redocly` command available on your system. +- [Install locally, using `npm`](#install-locally) to make the `redocly` command available on your system. - [Use `npx` to get the tool at runtime](#use-the-command-at-runtime) rather than installing it. -- The command is also [available via Docker](#docker) if you'd prefer to use it that way. +- The command is also [available through Docker](#docker). -## Install globally +## Install locally -{% admonition type="success" name="Tip" %} -Make sure you have the newest version of `npm` before you begin. -{% /admonition %} +Before you begin, make sure you have the newest version of `npm`. -Install the tool with the following command: +To install Redocly CLI locally: -```shell -npm i -g @redocly/cli@latest +1. In your CLI, `cd` to your project's directory. +1. Enter the following command: + +```bash +npm i @redocly/cli@latest ``` -Running `redocly --version` confirms that the installation was successful, and the currently-installed version of the tool. +1. (Optional) Run `redocly --version` to confirm that the installation was successful and the currently-installed version of the tool. ## Use the command at runtime -[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is npm's package runner. It installs and runs a command without installing it globally. You might use this where you can't install a new command, or in a CI context where the command is only used a handful of times. +[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is `npm`'s package runner. +It installs and runs a command without installing it globally. -To run Redocly CLI with `npx`, the command looks like the following example: +Use this approach where you can't install a new command, or in a CI context where the command is only used a handful of times. -```shell -npx @redocly/cli@latest [options] -``` +To run Redocly CLI with `npx`: + +- Replace `redocly` with `npx @redocly/cli@latest` to prepend Redocly CLI commands. + + ```bash + npx @redocly/cli@latest [options] + ``` For example, to run `redocly lint` on a file named `openapi.yaml`, use the following command: -```shell +```bash npx @redocly/cli@latest lint openapi.yaml ``` -Replace `redocly` with `npx @redocly/cli@latest` to prepend to other commands you see in documentation. - ## Run commands inside Docker Redocly CLI is available as a pre-built Docker image in [Docker Hub](https://hub.docker.com/r/redocly/cli) and [GitHub Packages](https://github.com/Redocly/redocly-cli/pkgs/container/cli). -Install [Docker](https://docs.docker.com/get-docker/) if you don't have it already, then pull the image with the following command: +Before you begin, make sure you have Docker [installed](https://docs.docker.com/get-docker/). + +To run Redocly CLI commands inside a docker container: + +1. Pull the image: + {% tabs %} {% tab label="Docker Hub" %} -```shell +```bash docker pull redocly/cli ``` {% /tab %} {% tab label="GitHub Packages" %} -```shell +```bash docker pull ghcr.io/redocly/cli ``` {% /tab %} {% /tabs %} -To give a Docker container access to your OpenAPI description files, you need to mount the containing directory as a volume. Assuming the API description is in the current working directory, the command to use is: -```shell Example with lint command +1. To give a Docker container access to your OpenAPI description files, mount the containing directory as a volume: + +```bash Example with lint command docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml ``` +This example assumes that the API description file is in your current working folder. + ## Run CLI behind a proxy -If you need to run the CLI tool behind a proxy, you can use the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to configure the proxy settings. These environment variables are commonly used to specify the proxy server for HTTP and HTTPS traffic, respectively. +To run the CLI tool behind a proxy, you can use the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to configure the proxy settings. +These environment variables specify the proxy server for HTTP and HTTPS traffic, respectively. ### Set up Proxy Environment Variables -Before running the CLI behind a proxy, make sure to set the appropriate proxy environment variables. Open a terminal and use the following commands: +To set the proxy environment variables: + +- Open a terminal and use the following command: + +{% tabs %} +{% tab label="HTTP proxy" %} ```bash -# For HTTP proxy export HTTP_PROXY=http://your-http-proxy-server:port +``` -# For HTTPS proxy +{% /tab %} +{% tab label="HTTPS proxy" %} + +```bash export HTTPS_PROXY=https://your-https-proxy-server:port ``` +{% /tab %} +{% /tabs %} + ### Use Environment Variables with CLI Commands -You can also directly include the proxy environment variables in the command itself. For example: +To directly include the proxy environment variables in a Redocly CLI command: -```bash -HTTPS_PROXY=https://your-https-proxy-server:port redocly lint --extends minimal openapi.yaml -``` +- Prepend the command with the environment variable and its value. + + For example: + + ```bash + HTTPS_PROXY=https://your-https-proxy-server:port redocly lint --extends minimal openapi.yaml + ``` ## Next steps diff --git a/docs/@v2/installation.md b/docs/@v2/installation.md index 63fbb66a89..6c00c5dd53 100644 --- a/docs/@v2/installation.md +++ b/docs/@v2/installation.md @@ -2,92 +2,120 @@ Choose the most appropriate installation method for your needs: -- [Install locally, using `npm`](#install-globally) to make the `redocly` command available on your system. +- [Install locally, using `npm`](#install-locally) to make the `redocly` command available on your system. - [Use `npx` to get the tool at runtime](#use-the-command-at-runtime) rather than installing it. -- The command is also [available via Docker](#docker) if you'd prefer to use it that way. +- The command is also [available through Docker](#docker). -## Install globally +## Install locally -{% admonition type="success" name="Tip" %} -Make sure you have the newest version of `npm` before you begin. -{% /admonition %} +Before you begin, make sure you have the newest version of `npm`. -Install the tool with the following command: +To install Redocly CLI locally: -```shell -npm i -g @redocly/cli@latest +1. In your CLI, `cd` to your project's directory. +1. Enter the following command: + +```bash +npm i @redocly/cli@latest ``` -Running `redocly --version` confirms that the installation was successful, and the currently-installed version of the tool. +1. (Optional) Run `redocly --version` to confirm that the installation was successful and the currently-installed version of the tool. ## Use the command at runtime -[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is npm's package runner. It installs and runs a command without installing it globally. You might use this where you can't install a new command, or in a CI context where the command is only used a handful of times. +[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is `npm`'s package runner. +It installs and runs a command without installing it globally. -To run Redocly CLI with `npx`, the command looks like the following example: +Use this approach where you can't install a new command, or in a CI context where the command is only used a handful of times. -```shell -npx @redocly/cli@latest [options] -``` +To run Redocly CLI with `npx`: + +- Replace `redocly` with `npx @redocly/cli@latest` to prepend Redocly CLI commands. + + ```bash + npx @redocly/cli@latest [options] + ``` For example, to run `redocly lint` on a file named `openapi.yaml`, use the following command: -```shell +```bash npx @redocly/cli@latest lint openapi.yaml ``` -Replace `redocly` with `npx @redocly/cli@latest` to prepend to other commands you see in documentation. - ## Run commands inside Docker Redocly CLI is available as a pre-built Docker image in [Docker Hub](https://hub.docker.com/r/redocly/cli) and [GitHub Packages](https://github.com/Redocly/redocly-cli/pkgs/container/cli). -Install [Docker](https://docs.docker.com/get-docker/) if you don't have it already, then pull the image with the following command: +Before you begin, make sure you have Docker [installed](https://docs.docker.com/get-docker/). + +To run Redocly CLI commands inside a docker container: + +1. Pull the image: + {% tabs %} {% tab label="Docker Hub" %} -```shell +```bash docker pull redocly/cli ``` {% /tab %} {% tab label="GitHub Packages" %} -```shell +```bash docker pull ghcr.io/redocly/cli ``` {% /tab %} {% /tabs %} -To give a Docker container access to your OpenAPI description files, you need to mount the containing directory as a volume. Assuming the API description is in the current working directory, the command to use is: -```shell Example with lint command +1. To give a Docker container access to your OpenAPI description files, mount the containing directory as a volume: + +```bash Example with lint command docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml ``` +This example assumes that the API description file is in your current working folder. + ## Run CLI behind a proxy -If you need to run the CLI tool behind a proxy, you can use the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to configure the proxy settings. These environment variables are commonly used to specify the proxy server for HTTP and HTTPS traffic, respectively. +To run the CLI tool behind a proxy, you can use the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to configure the proxy settings. +These environment variables specify the proxy server for HTTP and HTTPS traffic, respectively. ### Set up Proxy Environment Variables -Before running the CLI behind a proxy, make sure to set the appropriate proxy environment variables. Open a terminal and use the following commands: +To set the proxy environment variables: + +- Open a terminal and use the following command: + +{% tabs %} +{% tab label="HTTP proxy" %} ```bash -# For HTTP proxy export HTTP_PROXY=http://your-http-proxy-server:port +``` -# For HTTPS proxy +{% /tab %} +{% tab label="HTTPS proxy" %} + +```bash export HTTPS_PROXY=https://your-https-proxy-server:port ``` +{% /tab %} +{% /tabs %} + ### Use Environment Variables with CLI Commands -You can also directly include the proxy environment variables in the command itself. For example: +To directly include the proxy environment variables in a Redocly CLI command: -```bash -HTTPS_PROXY=https://your-https-proxy-server:port redocly lint --extends minimal openapi.yaml -``` +- Prepend the command with the environment variable and its value. + + For example: + + ```bash + HTTPS_PROXY=https://your-https-proxy-server:port redocly lint --extends minimal openapi.yaml + ``` ## Next steps