init, hooks, and build
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
The liblab init command simplifies SDK generation with an interactive setup that creates a liblab config file. It guides you through key configuration options directly in the CLI, allowing you to define settings without manually editing the configuration file.
liblab init
Running this command initializes SDK generation by creating a liblab.config.json file in your current directory. This file contains configuration settings for SDK generation.
By default, liblab init launches an interactive flow that lets you define key configuration options within the CLI, speeding up the setup process. The interactive prompts include:
- Location of your API specification file: Enter a file path or press Enter to use the sample spec.
- SDK languages: Select the programming languages of the generated SDKs.
- Project name: Enter the name of your project.
- Project license: Choose a license type.
- Build SDK now: (Optional) Choose to generate the SDK immediately after initialization.
If you build the SDK during initialization, liblab will validate your OpenAPI specification and generate the SDK.
Optional parameters
You can add parameters when running liblab init to change the default behavior:
liblab init [-f] [-g] [-h] [-s <value>] [-y] [-b]
The following table describes the available parameters:
| Parameter | Description |
|---|---|
-b, --build | Builds the SDK immediately after initialization. |
-f, --force | Overwrites an existing configuration file without prompting for confirmation. |
-g, --github | Creates a GitHub Actions workflow file (.github/workflows/build.yml) to automate SDK generation. This will create a .github/workflows/build.yml file that is configured to generate your SDK when the Action is manually run. Check the Integrate with GitHub Actions page for more details. |
-h, --hooks | Creates a hooks folder in your current directory to store SDK customization hooks. Learn more in the Hooks tutorial. |
-s, --spec=<value> | Specifies the path or URL to your API specification file. If using a local file, the path must be relative to the directory where you're running the CLI. |
-y, --default | Uses default configuration settings without prompting for user input. |
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 you generate. 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 the Terraform provider uses, and the customPlanModifiers folder contains the Terraform provider plan modifiers code.
Learn more about hooks in the 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
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.
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. The entire hooks folder will be deleted if you do not specify the language.
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
The liblab build command generates an SDK and documentation for your API using the configuration defined in your liblab.config.json file:
liblab build
This command validates your configuration file and performs a non-interactive validation of your API specification.
Optional parameters
You can add parameters when running liblab build to change the default behavior:
liblab build [--approve-docs]
[--skip-validation]
[--yes]
[--liblab-config=<value>]
[--language=<language>]
[--pr]
[--org=<value>]
The following table describes the available parameters:
| Parameter | Description |
|---|---|
--approve-docs | Approve documentation without review and publish it automatically to the liblab docs site. This is useful for CI/CD pipelines. |
--skip-validation | Skip API spec validation and proceed with SDK generation. |
--yes -y | Automatically confirm all prompts, including ignoring validation errors, approving docs, and overwriting SDKs. Useful for CI/CD pipelines. |
--liblab-config=<value> | Specify a custom configuration file path. If not set, the default path is liblab.config.json in the current working directory. |
--language=<value> -l | Generate an SDK for a specific programming language. For example, liblab build --language python generates only the Python SDK. If not set, SDKs are generated for all languages in the config file. |
--pr | Automatically create a pull request once SDKs are generated. Equivalent to running liblab pr. |
--org=<value> -o <value> | Specify the GitHub organization to create the PR in. Overrides the organization set in the config file. |
--platform=<option> -p <option> | Specify the platform where the PR should be created. Options: github, gitlab, bitbucket. |
Spec validation
You may encounter spec validation warnings during build. These are often harmless and can be ignored and fixed later. The output/api-schema-validation.json file will contain all validation warnings that you can use to review and improve your OpenAPI spec.
You can use the --skip-validation flag to skip validation by default:
liblab build --skip-validation
SDK programming language
When you run liblab build, it generates 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.
Output folder
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
Create a PR
You can also automatically create a pull request once the SDKs are generated using the --pr option:
liblab build --pr --org=my-org --platform=github
This is the same as running liblab pr after the SDK generation is complete.
If you don't inform the --org and --platform, liblab will use the information available in the liblab.config.json file.