Skip to main content

Quickstart with CLI

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.

Before getting started​

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

  • A GitHub account, used for authenticating with Stainless.

  • An OpenAPI spec, 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 or use an example spec.

Install the CLI​

warning

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.

brew install stainless-api/tap/stl

See more installation directions at the stainless-api/stainless-api-cli repository.

Authenticate the CLI​

Login to your account with:

stl auth login

Once signed in, you will be directed to create a Stainless organization. Complete the form on the website.

note

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

Create a project​

Initialize your project with

stl init

This will guide you through creating your project, running the first build, and setting up your Stainless workspace.

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

📁 <root>
├── 📄 openapi.json
├── 📄 stainless-workspace.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": "./<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.

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.

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.

Iterating on your SDKs​

stl dev​

Running stl dev will open a development server. 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 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.
note

You can also automatically trigger builds through GitHub Actions or a persistent link.

Next steps​

Configure your SDK​

The Stainless SDK generator is built with customizability in mind, letting you configure the SDK structure, client options, type names, and more.

Publish your SDK​

Once the SDK is functional (though perhaps not yet perfect), share it with the broader public by publishing to a package registry.