---
title: Quickstart with CLI | Stainless
description: Generate idiomatic and polished SDKs for your API to drive faster integration, broader adoption, and quicker upgrades.
---

## Introduction

Idiomatic and polished SDKs for your API drive faster integration, broader adoption, quicker upgrades, and trust in your engineering quality.

In this guide, you will generate SDKs from your OpenAPI specification that can be shipped as a beta to your users. You can iterate from there, polishing and shaping the SDKs.

This quickstart walks you through setting up a new project using the Stainless CLI. If you’d prefer to use the Stainless dashboard instead, check out the [dashboard quickstart guide](/docs/index.md).

### Before getting started

To get the most out of this guide, you’ll need:

- A [GitHub](https://github.com) account, used for authenticating with Stainless.

- An [OpenAPI spec](https://swagger.io/specification/), which is a standard way of describing your API shape. Stainless reads from this specification to generate SDKs.

  If you don’t yet have an OpenAPI spec, you can [create one](/docs/guides/create-openapi-spec/index.md) or [use an example spec](https://learn.openapis.org/examples/v3.0/petstore-expanded.html).

## 1 Install the CLI

The CLI is experimental. Please feel free to use it, but do not use it as a part of automated scripts as the structure may change over time.

Terminal window

```
brew install stainless-api/tap/stl
```

See more installation directions at the [stainless-api/stainless-api-cli](https://github.com/stainless-api/stainless-api-cli#installation) repository.

## 2 Authenticate the CLI

Login to your account with:

Terminal window

```
stl auth login
```

Once [signed in](https://app.stainless.com/login), you will be directed to create a Stainless organization. Complete the form on the website.

If you believe you should have access to an organization someone else invited you to, accept their invitation first to access your Stainless organization.

## 3 Create or connect a project

Initialize a project workspace with

Terminal window

```
stl init
```

This will guide you through either creating a project or linking an existing project to the local workspace.

Once you’re done going through the command line wizard, you should be left with a project that looks like:

```
📁 <root>
├─ 📁 .stainless/
│  ├─ 📄 workspace.json
│  ├─ 📄 openapi.json
│  └─ 📄 stainless.yml
└─ 📁 <project>-typescript/
   ├─ 📄 README.md
   ├─ 📄 CONTRIBUTING.md
   └─ 📁 src/
```

### The `.stainless/workspace.json` file

The Stainless workspace file declares the workspace that the CLI operates on. The workspace includes what project you’re working on and where your OpenAPI spec, Stainless config, and target outputs live relative to your workspace.

```
{
  "project": "<project-name>",
  "openapi_spec": "./openapi.json",
  "stainless_config": "./stainless.yml",
  "targets": {
    "typescript": {
      "output_path": "../sdks/<project-name>-typescript"
    }
  }
}
```

When you invoke `stl` from a directory with a `.stainless/workspace.json` or any sub-directory, it will know via the workspace what project to work on and where the files should go.

### The `stainless.yml` file

The Stainless config defines how to interpret your OpenAPI spec into idiomatic SDKs.

While your OpenAPI spec includes much of the information needed to generate an SDK, it doesn’t include necessary components like the SDK structure, pagination, publishing settings, and more.

Stainless uses both your OpenAPI spec and Stainless config to generate your SDKs. As part of your first generation, we create an initial draft of your Stainless config using an LLM.

When we make improvements to SDKs and the Stainless config that aren’t backwards-compatible, we release new [editions](/docs/reference/config#editions/index.md) you can opt-in to when you’re ready.

## 4 Try your SDKs

Once your build completes successfully, your SDKs are ready to use.

Each of our SDKs have shell scripts such as `./scripts/bootstrap` and `./scripts/test`.

Terminal window

```
cd <project>-typescript
./scripts/bootstrap
```

You can read more about how to add custom code and work with the repository by consulting the `CONTRIBUTING.md` of each SDK repository.

## 5 Iterating on your SDKs

### `stl preview`

Running `stl preview` builds the project based on the state of your local OpenAPI spec and Stainless config. This opens a Terminal User Interface (TUI) which shows you the progress of builds, the diagnostics they emit, and links to the associated studio page, GitHub workflows, and commits.

A “build” includes:

- A push to your config repository, which tracks all configuration changes that Stainless sees. This can be used as a log of the changes pushed to stainless.
- A push to your **staging** repository, which is an internal repository under the `stainless-sdks` GitHub org.
- A push to your **production** repository if configured. This is the user-facing repository that we ask for you to link up.

You can run it in watch mode with `stl preview --watch`.

You can also trigger builds directly with `stl builds create --branch <branch>` if you’d like to integrate builds as a part of your workflow.

### Troubleshooting

The Stainless generator always attempts to output something, even if it isn’t perfect.

When the generator detects potential improvements to the OpenAPI spec or the Stainless config, it raises *diagnostics*:

- **Error**: Indicates issues with the usability of the SDK, such as not being able to compile the library or make a request.
- **Warning**: Indicates major issues with the user experience of the SDK, but doesn’t affect usability of the rest of the SDK, such as an invalid schema or a misconfigured endpoint.
- **Note**: Indicates potential issues with the user experience of the SDK, but not too consequential for the user.

You can also automatically trigger builds through [GitHub Actions or a persistent link](/docs/guides/preview-builds/index.md).