# Redocly CLI quickstart guide

Take your first steps with the Redocly CLI by following the steps in this guide.

Before you start:

- [Install the Redocly CLI](/docs/cli/v1/installation) if you haven't already
- Create a new project folder and `cd` into the folder
- If you have an OpenAPI description to use, copy it into your project (we assume it's called `openapi.yaml`), or [try our example](https://github.com/Redocly/openapi-starter/blob/main/openapi/openapi.yaml)


There's also an [openapi-starter](https://github.com/Redocly/openapi-starter) repository that you can clone and experiment with to get your bearings

## Preview API documentation

Redocly CLI has support for showing a preview of [Redoc](https://redocly.com/redoc/) rendering your API docs, which updates when the API description updates.
Run the command:


```bash
redocly preview-docs openapi.yaml
```

The `redocly preview-docs` command triggers the creation of the doc preview for your API descriptions on your local machine. Once the doc preview has been generated, a url is printed as output to the CLI, as seen in the example below.

The API Doc preview takes a few moments to build. Upon completion, it provides the host and port where the preview server runs - typically `http://localhost:8080`.

details
summary
Preview-docs command output

```text
Using Redoc community edition.
Login with redocly login or use an enterprise license key to preview with the premium docs.


  🔎  Preview server running at http://127.0.0.1:8080

  👀  Watching openapi-starter/openapi/openapi.yaml and all related resources for changes


Bundling...

Created a bundle for openapi-starter/openapi/openapi.yaml successfully
GET /: 18.123ms
GET /simplewebsocket.min.js: 4.256ms
GET /hot.js: 4.765ms
GET /openapi.json: 1.73ms
GET /favicon.ico: 1.556ms
```

Open that URL in your browser, and admire your lovely API documentation!

![Preview of API documentation](/assets/preview-docs.465d1753301554cea90c054f30231d494563e241987499df61819eef72025504.222b8b44.png)

## Lint an OpenAPI description

Linting helps create consistent API descriptions and helps you avoid bugs, leading to a smoother developer experience. Using linting as part of your API workflow optimizes maintainability, facilitates ease of onboarding, and increases the adoption of the API.

The `lint` command is used to check that the OpenAPI description is compliant with a set of rules. To get started using a default ruleset, try the following command:


```bash
redocly lint --extends minimal openapi.yaml
```

The command uses a [minimal ruleset](/docs/cli/v1/rules/minimal) to lint the API description, and outputs a report of whether the API met the expected standard, as shown in the following example:


```text
validating openapi-starter/openapi/openapi.yaml...
[1] openapi-starter/openapi/openapi.yaml:72:10 at #/servers/1/url

Server `url` should not point to example.com or localhost.

70 |         default: www
71 |         description: Your tenant id
72 |   - url: https://example.com/api/v1
73 | paths:
74 |   '/users/{username}':

Warning was generated by the no-server-example.com rule.


openapi-starter/openapi/openapi.yaml: validated in 109ms

Woohoo! Your API description is valid. 🎉
You have 1 warning.
```

The output shows any aspects where the OpenAPI doesn't meet the standard. If you get too much output, try adding the `--format summary` parameter to the command.

Feeling brave and highly API compliant? Try the `recommended` standard instead and see how yours measures up.

## Craft a custom ruleset

Redocly CLI has some [great built-in rules](/docs/cli/v1/rules/built-in-rules), and you can use these to build up a ruleset that works for you.

For example, let's build a lightweight ruleset using the [minimal ruleset](/docs/cli/v1/rules/minimal) and adding some built-in rules to create a custom ruleset. You can see an example in the following snippet:


```yaml
extends:
 - minimal

rules:
  path-parameters-defined: error
  operation-operationId: error
  paths-kebab-case: warn
```

By taking the existing ruleset and adding some rule configuration, we can alter the rules and make a ruleset that suits our use case. Use this example as a starting point and then iterate to create a configuration that fits your needs.

## Next steps

After this quick tour of Redocly CLI, you can spend more time in the areas that interest you. Try one of the following:

- Check the [list of CLI commands](/docs/cli/v1/commands) to find out what else you can do and get more information about each command.
- Add some [configurable rules](/docs/cli/v1/rules/configurable-rules) to your setup for anything you need that doesn't have a built-in rule.
- [Use Redocly CLI with GitHub Actions](https://redocly.com/blog/consistent-apis-redocly-github-actions) for repeatably awesome API governance.