Documentation for the SDK Generator SDK.
⚙️ This project also comes with CLI tools and commands for ease of use
👷 This project also provides actions for workflow integration
SDKGeneratorManagerConfiguration is the configuration structure used by the SDK manager. It is the main mechanism for passing configuration values into the manager.
The same configuration model is reused by the related CLI entrypoints where applicable.
Fields:
-
Input : string- path to tool definition file (required) -
Output : string- destination of the generated code (required) -
Overwrite : bool- regenerate all files (required) -
TargetedGoVersion : string- targeted go version for the tool (required)
The manager interface of the SDK is ISDKGeneratorManager.
Mocks for this interface are provided under mocks/ using mockgen, so tests can target the interface rather than a concrete implementation.
Methods:
Description: Generate the tool
Signature:
Generate(ctx context.Context, logger logs.Loggers) (err error)Arguments:
-
ctx : context.Context- controls cancellation, deadlines, and other request-scoped values. -
logger : logs.Loggers- Logger to use for informational generation messages
Returns:
err : error- Whether the generation failed or not
Description: CLI for generating SDK/CLI go tools from a specification following schema
Configuration loading:
The CLI uses configUtils.LoadUsing(...) together with Viper.
Environment variables are prefixed with SDK_GENERATOR.
For workflow integration, prefer the actions when one of them already represents the step you want to run. GitHub can then validate the action metadata and execute the step in a more structured way. When looping, custom orchestration, or more complex parallel execution is needed, it can be preferable to install the binary first and call it directly from later workflow steps.
Effective precedence for command configuration is:
- keyring values, when the command enables keyring-backed loading and a non-empty value is available
- flag values provided on the command line
- environment variables, including values loaded from
.env - the configured configuration file, when one is configured and present and its format is supported by Viper
- default values
This CLI does not declare a dedicated configuration file path. The underlying loader still supports configuration files through Viper, but this tool does not configure a default configuration file location.
Configuration is loaded and validated at the start of command execution, so configuration errors are surfaced before the underlying manager logic runs.
CLIs expose separate runtime configuration for normal logging and structured annotations.
CLI defaults:
logger=consoleannotation=none
Action defaults:
logger=richannotation=github
Logger modes:
console: use the standard generated console logger.rich: use a richer terminal logger built with Charmbracelet Log.file: write normal logs to the path selected bylogger_file.none: disable normal log output.custom: use the logger implementation registered by the application during initialisation.
Annotation modes:
- Annotations are structured status messages separate from normal logs. They are primarily intended for CI systems that can render errors, warnings, and notices with extra context.
github: emit GitHub Actions-compatible structured annotations usinggolang-utilsannotation support.none: disable structured annotation output.
Logging and annotations are independent concerns. For example:
logger=richwithannotation=nonegives richer human-readable terminal logging without CI annotations.logger=richwithannotation=githubgives richer terminal logging together with GitHub-compatible annotations, which fall back to standard output.logger=nonewithannotation=githubsuppresses normal logs while still allowing advanced GitHub annotations.
Usage examples:
go-sdk-generator generate --logger=consolego-sdk-generator generate --logger=richgo-sdk-generator generate --logger=file --logger-file=tool.loggo-sdk-generator generate --logger=nonego-sdk-generator generate --logger=customgo-sdk-generator generate --annotation=githubgo-sdk-generator generate --logger=rich --annotation=githubTo use logger=custom, register CustomLoggerDefinition during application initialisation.
Add a file under cmd/generator/ in package generator.
package generator
import (
"log/slog"
"os"
baselogs "github.com/ARM-software/golang-utils/utils/logs"
)
func init() {
logger, err := baselogs.NewSlogLogger(slog.New(slog.NewJSONHandler(os.Stderr, nil)), "go-sdk-generator")
if err != nil {
panic(err)
}
CustomLoggerDefinition = logger
}The command-line user does not supply an arbitrary Go implementation through the CLI.
Selecting logger=custom simply chooses the implementation already registered by the application.
If logger=custom is selected without registering CustomLoggerDefinition, the generated CLI returns an error.
Skills:
Linux packages built for this tool also install the skills related to the tool under /etc/go-sdk-generator/.agents/skills.
OCI images are also published to ghcr.io/arm-software/go-sdk-generator for CI integration, reproducible builds, and workflows that prefer not to install the tool locally.
GitHub documents container-registry authentication and package permissions at:
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry
On a local machine, if the package is not publicly accessible to the user's
account yet, log in to ghcr.io first. With the GitHub CLI installed and
already authenticated:
gh auth token | docker login ghcr.io -u "$(gh api user --jq .login)" --password-stdinIf docker run or docker pull fails with 403 Forbidden, the GitHub
credentials usually do not have package-read access. The read:packages
permission is required, including in CI workflows that need to pull the OCI
image. For local-machine use with GitHub CLI credentials, refresh GitHub CLI
credentials, then log in to GHCR again:
docker logout ghcr.io
gh auth refresh --scopes read:packages
gh auth token | docker login ghcr.io -u "$(gh api user --jq .login)" --password-stdinPublished variants:
:v<version>-alpine:v<version>-ubuntu
Use exact release tags or image digests when the workflow must stay reproducible.
Description: Generate tool/project scaffolding. Run
go mod tidyafterwards to resolve the generated module dependencies, then rungo generate ./...to execute any generated code-generation directives inside the new project.
Usage:
go-sdk-generator generate [flags]OCI usage:
docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-alpine generate [flags]docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-ubuntu generate [flags]Flags and environment bindings:
You can pass values as flags on the command line or by setting the corresponding environment variables.
Example flag usage:
go-sdk-generator generate --annotation <value>Example environment usage:
SDK_GENERATOR_ANNOTATION=<value> go-sdk-generator generate| Configuration | Flag | Short | Environment | Required | Description |
|---|
| Annotation (shared) | --annotation | - | SDK_GENERATOR_ANNOTATION | no | Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. |
| Logger (shared) | --logger | - | SDK_GENERATOR_LOGGER | no | Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. |
| LoggerFile (shared) | --logger-file | - | SDK_GENERATOR_LOGGER_FILE | no | Path to write normal runtime logs when logger is set to file. |
| ShowConfig (shared) | --show-config | - | SDK_GENERATOR_SHOW_CONFIG | no | Show the effective configuration used by this command before execution. |
| Generate | --overwrite | -a | SDK_GENERATOR_OVERWRITE | no | regenerate all files |
| Input | --input | -i | SDK_GENERATOR_INPUT | yes | path to tool definition file |
| Output | --output | -o | SDK_GENERATOR_OUTPUT | yes | destination of the generated code |
| Summary | --summary | - | SDK_GENERATOR_SUMMARY | no | Write a human-readable summary to the selected destination. Allowed values: file, github, output. |
| SummaryFile | --summary-file | - | SDK_GENERATOR_SUMMARY_FILE | no | Path to the summary file when summary is set to file |
| TargetedGo | --go-version | -g | SDK_GENERATOR_GO_VERSION | no | targeted go version for the tool |
Configuration type:
type GenerateConfiguration struct {
Annotation GenerateAnnotation `mapstructure:"annotation"`
Generate bool `mapstructure:"overwrite"`
Input string `mapstructure:"input"`
Logger GenerateLogger `mapstructure:"logger"`
LoggerFile string `mapstructure:"logger_file"`
Output string `mapstructure:"output"`
ShowConfig bool `mapstructure:"show_config"`
Summary GenerateSummary `mapstructure:"summary"`
SummaryFile string `mapstructure:"summary_file"`
TargetedGo string `mapstructure:"go_version"`
}Fields:
-
Annotation : GenerateAnnotation- Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. -
Generate : bool- regenerate all files -
Input : string- path to tool definition file (required) -
Logger : GenerateLogger- Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. -
LoggerFile : string- Path to write normal runtime logs when logger is set to file. -
Output : string- destination of the generated code (required) -
ShowConfig : bool- Show the effective configuration used by this command before execution. -
Summary : GenerateSummary- Write a human-readable summary to the selected destination. Allowed values: file, github, output. -
SummaryFile : string- Path to the summary file when summary is set to file -
TargetedGo : string- targeted go version for the tool
Helper methods:
Validate()validates the configuration.
func (cfg *GenerateConfiguration) Validate() errorDefaultGenerateConfiguration()returns the default values.
func DefaultGenerateConfiguration() *GenerateConfigurationDescription: Run
go-sdk-generator schemato dump the embedded manifest schema as JSON for agents and other tooling
Usage:
go-sdk-generator schema [flags]OCI usage:
docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-alpine schema [flags]docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-ubuntu schema [flags]Flags and environment bindings:
You can pass values as flags on the command line or by setting the corresponding environment variables.
Example flag usage:
go-sdk-generator schema --annotation <value>Example environment usage:
SDK_GENERATOR_ANNOTATION=<value> go-sdk-generator schema| Configuration | Flag | Short | Environment | Required | Description |
|---|
| Annotation (shared) | --annotation | - | SDK_GENERATOR_ANNOTATION | no | Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. |
| Logger (shared) | --logger | - | SDK_GENERATOR_LOGGER | no | Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. |
| LoggerFile (shared) | --logger-file | - | SDK_GENERATOR_LOGGER_FILE | no | Path to write normal runtime logs when logger is set to file. |
| ShowConfig (shared) | --show-config | - | SDK_GENERATOR_SHOW_CONFIG | no | Show the effective configuration used by this command before execution. |
Configuration type:
type SchemaConfiguration struct {
Annotation SchemaAnnotation `mapstructure:"annotation"`
Logger SchemaLogger `mapstructure:"logger"`
LoggerFile string `mapstructure:"logger_file"`
ShowConfig bool `mapstructure:"show_config"`
}Fields:
-
Annotation : SchemaAnnotation- Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. -
Logger : SchemaLogger- Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. -
LoggerFile : string- Path to write normal runtime logs when logger is set to file. -
ShowConfig : bool- Show the effective configuration used by this command before execution.
Helper methods:
Validate()validates the configuration.
func (cfg *SchemaConfiguration) Validate() errorDefaultSchemaConfiguration()returns the default values.
func DefaultSchemaConfiguration() *SchemaConfigurationDescription: Run
go-sdk-generator agent --initto initialise the repo skills under .agents/skills
Usage:
go-sdk-generator agent [flags]OCI usage:
docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-alpine agent [flags]docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-ubuntu agent [flags]Flags and environment bindings:
You can pass values as flags on the command line or by setting the corresponding environment variables.
Example flag usage:
go-sdk-generator agent --annotation <value>Example environment usage:
SDK_GENERATOR_ANNOTATION=<value> go-sdk-generator agent| Configuration | Flag | Short | Environment | Required | Description |
|---|
| Annotation (shared) | --annotation | - | SDK_GENERATOR_ANNOTATION | no | Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. |
| Logger (shared) | --logger | - | SDK_GENERATOR_LOGGER | no | Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. |
| LoggerFile (shared) | --logger-file | - | SDK_GENERATOR_LOGGER_FILE | no | Path to write normal runtime logs when logger is set to file. |
| ShowConfig (shared) | --show-config | - | SDK_GENERATOR_SHOW_CONFIG | no | Show the effective configuration used by this command before execution. |
| Init | --init | - | SDK_GENERATOR_INIT | no | install the embedded skills into the current repository |
Configuration type:
type AgentConfiguration struct {
Annotation AgentAnnotation `mapstructure:"annotation"`
Init bool `mapstructure:"init"`
Logger AgentLogger `mapstructure:"logger"`
LoggerFile string `mapstructure:"logger_file"`
ShowConfig bool `mapstructure:"show_config"`
}Fields:
-
Annotation : AgentAnnotation- Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. -
Init : bool- install the embedded skills into the current repository -
Logger : AgentLogger- Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. -
LoggerFile : string- Path to write normal runtime logs when logger is set to file. -
ShowConfig : bool- Show the effective configuration used by this command before execution.
Helper methods:
Validate()validates the configuration.
func (cfg *AgentConfiguration) Validate() errorDefaultAgentConfiguration()returns the default values.
func DefaultAgentConfiguration() *AgentConfigurationGitHub Actions are also published so that go-sdk-generator subcommands can be used easily in CI workflows.
Prefer using the actions directly when they already represent one complete workflow step.
Prefer the installation action when the goal is only to obtain the tool for later workflow steps, for example when a later step needs to loop, pipe output, perform additional shell processing, or call a script that expects the tool to already be available in the environment.
This follows the same general model used by tool-installing actions such as goreleaser/goreleaser-action with install-only and anchore/sbom-action/download-syft.
Skill:
Actions in this repository:
actions/install-toolinstallsgo-sdk-generatoractions/generaterunsgo-sdk-generator generate
Use the published installation action to obtain the tool so it can be used in other workflow steps:
- name: Install go-sdk-generator from release
uses: ARM-software/go-sdk-generator/actions/install-tool@v0
with:
workdir: .toolsUse the published action from an official release to perform a particular action [generate] directly:
- name: Run go-sdk-generator generate
uses: ARM-software/go-sdk-generator/actions/generate@v0
with:
# provide the inputs required by the `generate` command hereThe actions expose inputs for selecting the release source and installation location.
For actions that perform a particular subcommand, the remaining inputs map onto that subcommand's CLI flags.
Every action also exposes the cmd output, which resolves to a usable reference for the installed go-sdk-generator command in later workflow steps.
Inputs:
action-repo: repository to download releases from; defaults to the repository running the actionworkdir: working directory where the CLI is run. If later workflow steps need to call the installed tool, use thecmdoutput rather than inferring its location from this directory.actions/install-toolexposes only installation inputs- each action other than the installation one also exposes one input per non-hidden CLI flag for that subcommand, including repeated root inputs shared across commands
- commands with positional operands also expose an
operandsinput, one operand per line
Outputs:
cmdoutput: a reference to the installedgo-sdk-generatorcommand for later workflow steps
The action resolves official releases from the action version:
@v0.29.0installs exactlyv0.29.0@v0.29installs the latestv0.29.xrelease@v0installs the latestv0.x.yrelease@latestinstalls the latest released version