> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borea.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build and deploy our first SDK in minutes

<Note>
  To get started you will need an API key for your account. Create one in your dashboard{' '}
  <a href="https://borea.dev/app/settings">settings</a>.
</Note>

### Initialize

<AccordionGroup>
  <Accordion icon="download" title="Install the CLI">
    *This is not a production command. Make an install script!*

    **Install using curl:**

    <CodeGroup>
      ```curl CURL theme={null}
      curl -L https://borea.dev/install.sh | bash
      ```
    </CodeGroup>

    **Verify the installation:**

    ```
    borea --version
    ```

    You should see an output like this: `Borea CLI: v.1.1.3`

    If not, rerun the script and verify again.
  </Accordion>

  <Accordion icon="gear" title="Configure your project">
    Configuring Borea is simple. We'll walk you through the basics on how to generate and use our powerful `borea.config.json` file.

    #### Run the `init` command

    ```
    borea init
    ```

    This will generate a default `borea.config.json` file that looks something like this:

    ```json borea.config.json theme={null}
      {
        "input": {
          "openapi": ["<path_to_spec_or_URL>"]
        },
        "output": {
          "clientSDK": "Formatted OpenAPI Title by default",
          "models": "models",
          "tests": true,
          "xCodeSamples": false
        },
        "ignores": []
      }
    ```

    By default, SDKs and data models are generated. **We highly recommend not changing this.** Tests are a premium feature and are disabled by default, and will not work on the Hobby plan.
    <Note>Command line arguments take precedence over  `borea.config.json`. You can overwrite the settings in the config file by passing the proper flags. For all options and flags, see <a href="/essentials/configuration">configuration</a></Note>

    #### Configuration options

    * `input`:
      * `openapi` - The relative/absolute path or URL to your OpenAPI spec file (json and yaml supported)
    * `output`:
      * `clientSDK` - The name of the SDK when generated. Default is the formatted title in your OpenAPI spec
      * `models` - The name of the folder to hold all the client models
      * `tests` - Enables test generation and running on regeneration
      * `xCodeSamples` - Enables generation of x-Code-Samples to be used in you OpenAPI spec and documentation
    * `ingores` - Folders and files here will be ignored on regeneration, preserving any changes. Glob (gitignore) syntax
  </Accordion>

  <Accordion icon="check" title="Validate your spec">
    <Note>Spec validation is not yet released. As a temporary substitute, we recommend using{' '}
    <a href="https://quobix.com/vacuum/start/">Vacuum</a></Note>
  </Accordion>
</AccordionGroup>

### Generate

<AccordionGroup>
  <Accordion icon="wrench" title="Generate SDK">
    #### Run `generate` command with your API key

    ```
    borea generate -k <your_api_key>
    ```

    You can create and manage API keys in your dashboard{' '}
    <a href="https://borea.dev/app/settings">settings</a>.
  </Accordion>

  <Accordion icon="terminal" title="Add custom code">
    There are many things that Borea does not yet support out of the box like OAuth, webhooks, and websockets.

    To implement these features, or any others you want, simply add the file or folder to the `ignores` field in `borea.config.json`.
    Any changes you make to those files or folders will be preserved on regeneration.

    ```json borea.config.json {11} theme={null}
      {
        "input": {
          "openapi": ["<path_to_spec_or_URL>"]
        },
        "output": {
          "clientSDK": "Formatted OpenAPI Title by default",
          "models": "models",
          "tests": true,
          "xCodeSamples": false
        },
        "ignores": ["webhooks.py", "lib/auth"]
      }
    ```

    <Note>Because of how the ignores system works, the generators will not write over your changes on regeneration,{' '}
    and therefore can lead to that code being misaligned with your API. We are working on a GitHub integration{' '}
    to allow for merge conflict resolution, but in the mean time we recommend you keep change's footprint small.</Note>
  </Accordion>

  <Accordion icon="vial-circle-check" title="Test your SDKs">
    <Note>Testing is not a live feature for Hobby or Growth users. Testing is currently done manually for Enterprise customers</Note>
  </Accordion>
</AccordionGroup>

### Deploy

<AccordionGroup>
  <Accordion icon="server" title="Push to remote repo (optional, but recommended)">
    <Steps>
      <Step title="Create a Remote Respository">
        Go to the remote hosting service you prefer and create a new repository.

        For future compatability with Borea version control, we recommend GitHub.
      </Step>

      <Step title="Push your new SDK">
        ```shell theme={null}
          git init
          git add .
          git commit -m "initial commit"
          git branch -M main
          git remote add origin <remote_repo_url>
          git push -u origin main

        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion icon="rocket-launch" title="Publish to remote registries">
    <Note>
      Work in Progress 🚧
      To deploy to PyPi, please follow this <a href="https://packaging.python.org/en/latest/tutorials/packaging-projects/">tutorial</a>
    </Note>
  </Accordion>
</AccordionGroup>

## Quickstart Resources

<CardGroup>
  <Card title="Configuration Guide" icon="sliders-simple" href="/guides/configuration">
    A full guide to configure the Borea generators, CI/CD pipeline, and deployment.
  </Card>

  <Card title="API Reference" icon="square-terminal" href="/api-reference">
    The full documentation of our public API.
  </Card>
</CardGroup>

```
```