Initialize and generate an SDK and docs

These commands allow you to prepare a spec for SDK generation, and generate SDKs and documentation.

Command	Description
liblab init	Create a new liblab config file
liblab hooks	Create hooks for your SDK
liblab build	Generate your SDK and Docs

liblab init

Initialize your SDK generation by creating a new liblab config file.

liblab init [--force]
            [--github]
            [--hooks]
            [--spec=<value>]

This will create a liblab.config.json file in your current directory. You can learn more about the config file in the config file documentation.

Optional parameters

Parameter	Description
--force -f	Overwrite an existing config file. If you already have a liblab.config.json file then by default liblab init will ask if you want to overwrite it. Pass --force to overwrite without needing confirmation.
--github -g	Create a GitHub workflow file for your SDK. This will create a .github/workflows/build.yml file that is configured to generate your SDK when the Action is manually run. You can learn more from our GitHub Actions tutorial
--hooks -h	Create a hooks folder in your current directory. This folder will contain all the hooks for your SDK. You can learn more about hooks in our hooks tutorial
--spec -s	The path to your API spec file. This can be a local path or a publicly reachable URL. For local paths, this needs to be relative to the location that the CLI is run from.

liblab hooks

Bootstrap or remove SDK hooks or custom plan modifiers.

Hooks allow you to customize the API invocation lifecycle, handling before a request is sent, when a response is received and when API errors occur. Custom plan modifiers allow you to customize the plan modifiers generated for a Terraform provider.

liblab hooks [add/remove] [--language=<language>]
                          [--liblab-config=<value>]

When you add hooks for one or more SDK languages, a hooks folder is created that contains your hooks code. You can create hooks for any of the SDK languages that you are generating. Just having the hooks folder is enough to enable hooks for your SDK, but you will need to add code to the hooks to make them do anything.

When you add hooks for a Terraform provider, 2 folders are created - a hooks folder and a customPlanModifiers folder. The hooks folder contains the hooks code for the underlying Go SDK that is used by the Terraform provider, and the customPlanModifiers folder contains the Terraform provider plan modifiers code.

You can learn more about hooks in our hooks guide.

Commands

Command	Description
add	Bootstrap SDK hooks. This will create a hooks folder in your current directory.
remove	Remove SDK hooks. This will delete the hooks folder in your current directory, or remove a single language folder from the hooks folder.

liblab hooks add

Bootstrap SDK hooks.

liblab hooks add [--language=<language>]
                 [--liblab-config=<value>]

This will create a folder called hooks containing boilerplate hook files for the SDK languages defined in your config file. For example, if your config file is configured to create Python and TypeScript SDKs:

{
    ...
    "languages": [
        "python", 
        "typescript"
    ]
}

Then after running liblab hooks add the hooks folder will look like this:

hooks
├── python
└── typescript

If one of your languages is terraform - the following structure will be created:

hooks
└── terraform // hooks for the Go SDK that is used by the Terraform provider
customPlanModifiers // hooks that are triggered on the `terraform plan` command
└── resources

note

If you already have a hooks folder, or a folder for an SDK language specified with the --language parameter, you will be asked if you want to overwrite it. If you choose not to overwrite, the hooks will not be added. If you choose to overwrite, any existing hooks code will be lost.

Optional parameters

Parameter	Description
--language -l	Add hooks for just the specified language. For example, run liblab hooks add --language python to add hooks for Python to either a new or existing hooks folder.
--liblab-config=<value>	The path to your liblab config file. This can be a local path or a publicly reachable URL. If this is not set, the default config file path is liblab.config.json in the current working directory. If --language is not set, the hooks are added for all the SDK languages listed in the config file.

liblab hooks remove

Remove SDK hooks.

liblab hooks remove [--language=<language>]

This will remove the hooks. If no language is specified, then all hooks will be removed. If the language is provided, then only the hooks for that language will be deleted.

note

Hooks are removed by deleting the relevant folder. If you specify the hooks language with the --language parameter, the hooks folder for that language will be deleted. If you do not specify the language, the entire hooks folder will be deleted.

If you have made any changes to the hooks code, these changes will be lost.

Optional parameters

Parameter	Description
--language -l	Remove hooks for just the specified language. For example, run liblab hooks remove --language python to remove hooks for Python without removing any hooks for any other languages.

liblab build

Generate an SDK and Docs for your API.

liblab build [--approve-docs]
             [--skip-validation]
             [--yes]
             [--liblab-config=<value>]
             [--language=<language>]
             [--pr]
             [--org=<value>]
             [--pr]
             [--org=<value>]

The build command uses your config file to define how to build your SDK. You can learn more about the config file in the config file overview documentation.

This command will validate your config file, and do a non-interactive validation of your API spec. If there are any errors, you will be asked if you want to continue or not. If you choose to continue, the SDKs will be generated, but they may not work as expected. You can ignore any validation errors without having to select Y by passing either the --yes or the --skip-validation flag.

liblab build --yes

Detected potential issues with the spec:
 >   Warning: Info object must have "contact" object.
 >   Error: Info "description" must be present and non-empty string.
 >   Warning: Operation "description" must be present and non-empty string.
 >   Warning: Operation tags must be defined in global tags.
Created api-schema-validation.log with the full linting results
? It is important to fix your spec before continuing with a build. Not fixing the spec may yield a subpar SDK and documentation. Would you like to attempt to build the SDK anyway? (Y/n) 

This command will generate SDKs for the languages defined in your config file, unless you specify a language with the --language parameter. If you set the --language parameter, only the SDK for that language will be generated.

Once the SDKs are generated, they are downloaded to the output folder. If you already have an SDK in the output folder, you will be asked if you want to overwrite it. If you choose not to overwrite, the SDKs will not be downloaded.

✓ TypeScript built
TypeScript# sdk already exists in: /workspaces/cli/output/typescript, do you want to overwrite it? (Y/n):

You can force the SDK generation to overwrite existing SDKs by passing the --yes flag.

liblab build --yes

Once docs are generated they will be hosted on-line and you will have the ability to preview or download them. You will also be asked to approve the docs for publishing to the liblab docs site.

✓ Java built
✓ Python built
✓ TypeScript built
✓ Doc built
SDKs downloaded successfully. You can find them inside the "output" folder
 Action   Link
 ──────── ────────────────────────────────────────────────────────────────────────────── 
 Preview  <link>
 Download <link>
? Would you like to approve and publish these docs now? (Y/n)

You can also automatically create a pull request once the SDKs are generated using the --pr option. This is the same as running liblab pr after the SDK generation is complete.

Optional parameters

Parameter	Description
--approve-docs	Approve docs without review. This will skip the docs review process and publish the docs automatically to the liblab docs site. This is used when running liblab build from a CI/CD pipeline, or other automation where there is no human interaction.
--skip-validation	Skip spec validation and attempt to build the SDKs. This is not recommended - if there are warnings or errors in the spec that you want to ignore, it is best practice to add these to the config file. You can read more on ignoring validation issues in the validationsToIgnore section of the config file documentation.
--yes	Automatically pass Y to all questions. This includes ignoring spec validation errors, approving docs, and overwriting any downloaded SDKs. This flag is particularly useful when running the SDK generation in a CI/CD pipeline.
--liblab-config <value>	The path to your liblab config file. This can be a local path or a publicly reachable URL. If this is not set, the default config file path is liblab.config.json in the current working directory.
--language -l	Generate an SDK for just the specified language. For example, run liblab build --language python to generate an SDK for Python without generating any SDKs for any other languages. The language you specify does not need to be defined in your config file. If this is not set, SDKs for all languages specified in the config file are generated.
--pr	Create a pull request once the SDKs are generated. This is the same as running liblab pr after the SDK generation is complete.
--org <org name> -o <org name>	If you are using the --pr flag, this sets the GitHub organization to create the PR in. This overrides the organization set in the config file.