Use generated CLIs

This guide covers how to install, configure, authenticate, and use a CLI generated by the SDK generator. 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.

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.
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:

$
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:

$
go mod tidy
$
go build .

An executable binary is created in the current directory. Run it directly, replacing <cli-name> with the actual name of the generated CLI binary:

$
./<cli-name> --help

To make the CLI available system-wide, move the binary to a directory in your PATH:

$
# macOS / Linux
$
mv ./<cli-name> /usr/local/bin/<cli-name>

After installation, you can invoke the CLI from any directory:

$
<cli-name> --help

Help files

Every command and subcommand supports the --help flag. Use it to discover available commands, flags, and usage instructions:

$
# Top-level help
$
<cli-name> --help
$
$
# Help for a command group
$
<cli-name> <command-group> --help
$
$
# Help for a specific command
$
<cli-name> <command-group> <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:

$
<cli-name> 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).

Basic authentication

To configure a username and password for Basic auth, run the following command, replacing the arguments with your actual credentials:

$
<cli-name> setup-auth basic <username> [password]

If you omit the password argument, the CLI will prompt you to enter it securely (input is hidden):

$
<cli-name> 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:

$
<cli-name> setup-auth api-key [value]

If you omit the value, the CLI prompts for it securely (input is hidden):

$
<cli-name> 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:

$
<cli-name> 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:

$
<cli-name> 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:

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:

$
<cli-name> setup-auth oauth authorization-code [flags]

The following flags are available to configure the authorization code flow:

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:<port>/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.

The following is an example of what the authorization code flow looks like in practice:

$
# First, save your client credentials (if not already done)
$
<cli-name> setup-auth oauth client-credentials \
>
  --client-id "abc123" \
>
  --client-secret "secret456"
$
$
# Then run the authorization code flow
$
<cli-name> 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.

$
<cli-name> 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:

$
<cli-name> 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:

$
<cli-name> 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:

$
<cli-name> 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:

$
export EDITOR=vim
$
<cli-name> 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.

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:

<cli-name> <command-group> <command> [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).

$
# 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:

Request bodies

For API operations that accept a request body (POST, PUT, PATCH), use the --body or --body-file flags:

$
# Inline JSON
$
my-api users create --body '{"name": "Alice", "email": "alice@example.com"}'
$
$
# From a file
$
my-api users create --body-file ./user.json

Output

All command responses are printed to stdout as pretty-printed JSON:

1
{
2
  "id": "user-123",
3
  "name": "Alice",
4
  "email": "alice@example.com"
5
}

Errors and warnings are printed to stderr, so you can safely pipe output to other tools:

$
# 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.

Skill file structure

Each skill file is located at skills/<group>-<command>/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.

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:

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 <cli-name> 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:

$
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:

$
MY_API_BASE_URL=https://api.example.com <cli-name> 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:<port>/callback is registered in your OAuth application settings.

Port conflict during OAuth

If port 8777 is already in use, specify a different port:

$
<cli-name> setup-auth oauth authorization-code --port 9999

Remember to update the redirect URI in your OAuth application settings to match.