*** title: Use generated CLIs max-toc-depth: 2 topictype: procedure --------------------- For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. For full content including API reference and SDK examples, see https://learning.postman.com/llms-full.txt. This guide covers how to install, configure, authenticate, and use a [CLI generated by the SDK generator](/docs/sdk-generator/overview). The generated CLI is a Go-based command-line tool that wraps a generated Go SDK, giving you terminal access to every operation in the underlying API. To generate a CLI, see [Generate CLI from your collection or specification](/docs/cli-generator/overview). ## Prerequisites The generated CLI requires installing Go on your system. To ensure you have the right setup, do the following: 1. Check the version specified in the project's `go.mod` file to find the minimum version that needs to be installed. 2. Install [Go](https://go.dev/dl/). 3. Verify installation. Run the `go version` command. You should see output similar to the following, confirming that Go is installed and showing the version number: ```bash go version go1.20.5 darwin/amd64 ``` ## Installation After receiving the generated CLI source code, build it from the project root. Run the following commands in your terminal: ```bash go mod tidy go build . ``` An executable binary is created in the current directory. Run it directly, replacing `` with the actual name of the generated CLI binary: ```bash ./ --help ``` To make the CLI available system-wide, move the binary to a directory in your `PATH`: ```bash # macOS / Linux mv ./ /usr/local/bin/ ``` After installation, you can invoke the CLI from any directory: ```bash --help ``` ## Help files Every command and subcommand supports the `--help` flag. Use it to discover available commands, flags, and usage instructions: ```bash # Top-level help --help # Help for a command group --help # Help for a specific command --help ``` ## Authentication If the API requires authentication, the CLI provides a `setup-auth` command with subcommands for each supported authentication method. Run `setup-auth --help` to see which methods are available for your generated CLI: ```bash setup-auth --help ``` ### Credentials storage All authentication credentials are stored locally in a JSON file at the following path: ``` ~/.cli-name/credentials ``` Where `cli-name` is the name of your generated CLI binary (for example, `~/.my-api/credentials`). * The directory is created with permissions `0700` (owner-only access). * The credentials file is written with permissions `0600` (owner read/write only). * Credentials persist across sessions. You only need to run `setup-auth` once (or when credentials change). ### Basic authentication To configure a username and password for Basic auth, run the following command, replacing the arguments with your actual credentials: ```bash setup-auth basic [password] ``` If you omit the password argument, the CLI will prompt you to enter it securely (input is hidden): ```bash setup-auth basic my-user # Password: ******** # Basic authentication credentials saved successfully. ``` ### API key authentication To configure an API key, run the following command, replacing the arguments with your actual API key value: ```bash setup-auth api-key [value] ``` If you omit the value, the CLI prompts for it securely (input is hidden): ```bash setup-auth api-key # API Key: ******** # API key authentication credentials saved successfully. ``` ### OAuth authentication OAuth authentication is managed through the `setup-auth oauth` subcommand group: ```bash setup-auth oauth --help ``` #### Client credentials flow To configure machine-to-machine authentication using OAuth 2.0 Client Credentials, run the following command, replacing the arguments with your actual client ID and secret: ```bash setup-auth oauth client-credentials \ --client-id "your-client-id" \ --client-secret "your-client-secret" ``` The following flags are available to configure the client credentials flow: OAuth client ID OAuth client secret OAuth token endpoint base URL The client ID and secret are saved to the credentials file and used automatically for all subsequent API calls that require OAuth authentication. #### Authorization code flow For interactive user authentication using OAuth 2.0 Authorization Code, run the following command, replacing the arguments with your actual values: ```bash setup-auth oauth authorization-code [flags] ``` The following flags are available to configure the authorization code flow: Comma-separated list of OAuth scopes to request. Local port for the OAuth callback server. Override the saved OAuth client ID. Override the saved OAuth client secret. To complete the authorization code flow, the CLI performs the following steps: 1. The CLI starts a temporary local HTTP server on `http://127.0.0.1:/callback`. 2. Your default browser opens to the authorization URL. 3. You log in and authorize the application in the browser. 4. The authorization server redirects back to the local callback URL with an authorization code. 5. The CLI exchanges the authorization code for access and refresh tokens. 6. The tokens are saved to `~/.cli-name/credentials` alongside your client ID and secret. Your OAuth application must be configured to allow `http://127.0.0.1:/callback` as a redirect URI (default port is `8777`). The following is an example of what the authorization code flow looks like in practice: ```bash # First, save your client credentials (if not already done) setup-auth oauth client-credentials \ --client-id "abc123" \ --client-secret "secret456" # Then run the authorization code flow setup-auth oauth authorization-code --scopes "read,write" # Opening browser for authorization... # If the browser does not open, visit this URL: # https://auth.example.com/authorize?client_id=abc123&redirect_uri=... # Waiting for authorization... # Authorization successful! ``` ## Configuration The `config` command enables you to manage CLI configuration settings such as the base URL for API requests. ```bash config --help ``` The configuration system allows you to customize CLI behavior through config files, environment variables, or command-line subcommands, with a clear precedence order for resolving conflicting values. ### Resolution order Configuration values are resolved in the following priority order (highest first): 1. **Environment variables** — Prefixed with the CLI name in uppercase with hyphens replaced by underscores (for example, for a CLI named `my-api`, the prefix is `MY_API_`). Example: `MY_API_BASE_URL`. 2. **Config file** — Located at `./config/config.yaml` relative to where the CLI is invoked. 3. **Built-in defaults** — Hardcoded in the generated SDK. ### Config subcommands The `config` command includes the following subcommands for managing configuration values: #### config set To set a configuration value in the local config file, run the following command, replacing the key and value with your configuration setting: ```bash config set base_url https://api.staging.example.com ``` This creates `./config/config.yaml` (if it doesn't exist) and writes the key-value pair. #### config get To read a configuration value (resolved from any source), run the following command, replacing the key with your configuration setting: ```bash config get base_url # base_url = https://api.staging.example.com ``` #### config list To list all configuration keys and their current resolved values, run the following command: ```bash config list # base_url = https://api.staging.example.com ``` #### config edit To edit the config file in your default editor (`$EDITOR` or `$VISUAL`), run the following commands: ```bash export EDITOR=vim config edit ``` ### Environment variables You can override any configuration key using environment variables. The environment variable name is formed by taking the CLI name (uppercase, hyphens → underscores) as a prefix, followed by the key name (uppercase). The following table shows examples of how configuration keys map to environment variables to a CLI. | CLI name | Config key | Environment variable | | :------------- | :--------- | :---------------------- | | `my-api` | `base_url` | `MY_API_BASE_URL` | | `petstore-cli` | `base_url` | `PETSTORE_CLI_BASE_URL` | ## Command usage The CLI follows a hierarchical structure with command groups and individual commands, uses flags for parameters, supports JSON request bodies, and outputs responses as pretty-printed JSON to facilitate easy integration with other tools. ### Command structure The generated CLI organizes API operations into a two-level hierarchy as follows: ``` [flags] ``` Where: * **Command groups** correspond to API services or resource categories (for example, `users`, `projects`, `billing`). * **Commands** within each group correspond to individual API operations (for example, `list`, `get`, `create`, `delete`). ```bash # List all users my-api users list # Get a specific user my-api users get --id "user-123" # Create a project my-api projects create --name "My Project" --body '{"description": "A new project"}' ``` ### Flags and parameters Commands accept flags that map to API parameters. All parameter types (path, query, and header) will map to a flag. Required flags are enforced, and the CLI will error if they're missing. #### Flag types Flags accept different value types depending on the API schema: | Type | Example | | :----------- | :---------------------- | | String | `--name "John"` | | Integer | `--page 1` | | Float | `--threshold 0.95` | | Boolean | `--verbose` | | String Array | `--tags "a" --tags "b"` | ### Request bodies For API operations that accept a request body (POST, PUT, PATCH), use the `--body` or `--body-file` flags: ```bash # Inline JSON my-api users create --body '{"name": "Alice", "email": "alice@example.com"}' # From a file my-api users create --body-file ./user.json ``` The `--body` and `--body-file` flags are mutually exclusive. Use `--help` on any command to see the expected body schema and an example. ### Output All command responses are printed to `stdout` as pretty-printed JSON: ```json { "id": "user-123", "name": "Alice", "email": "alice@example.com" } ``` Errors and warnings are printed to `stderr`, so you can safely pipe output to other tools: ```bash # Pipe JSON output to jq my-api users list | jq '.[].name' # Save response to a file my-api users get --id "user-123" > user.json ``` ## AI agent skills Alongside the CLI binary and source code, the generator produces a `skills/` directory containing one Markdown skill file per CLI command. These files are designed to be consumed by AI agents (such as Cursor, Copilot, or custom LLM-based tooling) so they can understand how to invoke each CLI command without guesswork. For more information on how AI agents can interact with the generated skills, see [Use generated CLIs with AI agents](/docs/cli-generator/cli-ai/). ### Skill file structure Each skill file is located at `skills/-/SKILL.md` and follows a structured format: A typical skill file contains the following sections: * **Frontmatter** — A `name` and `description`, giving the agent a quick summary of what the command does. * **Overview** — A human-readable description of the command's purpose, pulled from the API specification. * **Usage** — The full command syntax with all required and optional flags listed. * **Example** — A concrete, runnable example command with placeholder values provided. * **Parameters and Flags** — Tables organized by parameter location (path, query, header), showing each flag's name, type, whether it's required, its default value, and a description. * **Request Body** — Instructions for passing a JSON body through `--body` or `--body-file`, with inline and file-based examples. * **Examples** — Additional usage examples if they were provided during generation. ### Using skills with AI agents The skill files serve as structured documentation that AI agents can read to understand exactly how to construct CLI commands. Rather than relying on the agent to parse `--help` output at runtime, the skills provide all the information upfront in a format optimized for LLM consumption. These are some common ways to use the generated skills with AI agents: * **Cursor/IDE agents** — Place the generated CLI project (or just the `skills/` folder) in your workspace. Agents like Cursor can read the skill files to learn how to call any CLI command on your behalf. * **Custom automation** — If you're building an LLM-powered workflow that needs to call your API, point the agent at the `skills/` directory. Each file is self-contained and tells the agent exactly which flags are required, what types they expect, and how to pass a request body. * **Onboarding** — New team members (or their AI assistants) can browse the skill files to quickly understand the full surface area of the CLI without reading the API spec. ## CLI naming The name of the generated CLI binary is derived from your SDK configuration: * If `goModuleName` is provided in the CLI language options (for example, `github.com/my-org/my-api-cli`), the last path segment (`my-api-cli`) is used as the CLI name. * If only `sdkName` is provided (for example, `MyCli`), the SDK name is converted to kebab-case (`my-cli`) and used as the CLI name. * If neither is provided, the default name `go-cli` is used. The following examples show how different configurations affect the CLI name and Go module path: | `sdkName` | `goModuleName` | CLI binary name | Go module path | | :---------- | :----------------------------- | :-------------- | :----------------------------- | | `MyCli` | *(not set)* | `my-cli` | `github.com/my-cli` | | `PetStore` | `github.com/acme/petstore-cli` | `petstore-cli` | `github.com/acme/petstore-cli` | | *(not set)* | *(not set)* | `go-cli` | `github.com/go-cli` | ## Troubleshooting If you encounter issues with the generated CLI, refer to the following troubleshooting tips. ### "unknown config key" error You used an invalid key with `config set` or `config get`. Run ` config --help` to view the list of available configuration keys. ### Credentials aren't being applied Verify that the credentials file exists and contains the expected values: ```bash cat ~/.cli-name/credentials ``` Make sure you're using the correct CLI name in the path (the directory name matches the CLI binary name, prefixed with a dot). ### Config file not found The config file is read from `./config/config.yaml` relative to the directory where you invoke the CLI. If you need to use a different base URL, you can also set it using environment variables instead: ```bash MY_API_BASE_URL=https://api.example.com users list ``` ### OAuth authorization fails The CLI attempts to open your default browser automatically. If it fails, copy the authorization URL printed to `stderr` and open it manually. Make sure the redirect URI `http://127.0.0.1:/callback` is registered in your OAuth application settings. ### Port conflict during OAuth If port `8777` is already in use, specify a different port: ```bash setup-auth oauth authorization-code --port 9999 ``` Remember to update the redirect URI in your OAuth application settings to match.