Add Code Generation Support for Alternative Sources by bcdxn · Pull Request #19 · bcdxn/opencli

bcdxn · 2026-08-24T02:00:52Z

Alternative Sources

Although the OpenCLI Specification supported the concept of alternative sources (i.e. passing flag values from config files and environment variables) there was no support in the code generation within ocli. This branch adds that missing support. Now CLIs generated for Cobra, urfave/cli V3 and Yargs can all pull values from the specified config files/environment variables.

commands:

  pleasantries greet <name> [flags]:
    summary: "Say hello"
    args:
      - name: "name"
        summary: "A name to include in the greeting"
        required: true
        type: "string"
    flags:
      - name: "language"
        summary: "The language of the greeting"
        type: "string"
        choices:
          - value: "english"
          - value: "spanish"
        default: "English"
        alternativeSources:
           - type: "$ENV"
            property: "PLEASANTRIES_LANGUAGE"
          - type: "$FILE"
            property: "$.language"

Global Flags

This branch also addresses a major bug where global flags were dropped during code generation for some frameworks.

Copilot

🟡 Changes recommended

Yargs resolution currently breaks defaults, required flags, enum compilation, and source precedence, while Go YAML numeric coercion is incomplete.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds generated CLI support for environment- and config-file-backed flag values across Cobra, urfave/cli, and Yargs.

Changes:

Generates alternative-source resolvers and config loaders.
Adds global-flag propagation and generator coverage.
Updates examples, documentation, generated fixtures, and web navigation.

File summaries

File	Description
`gen/cli.go`	Validates unsupported group arguments/flags.
`gen/cli_cobra.go`	Generates Cobra source resolution.
`gen/cli_urfave_cli.go`	Generates urfave source resolution.
`gen/cli_yargs.go`	Generates Yargs source resolution.
`gen/templates/code/cobra/gencli/config.tmpl`	Adds Cobra config resolvers.
`gen/templates/code/cobra/gencli/run.tmpl`	Loads config and binds globals.
`gen/templates/code/cobra/gencli/params.tmpl`	Adds global-flag context helpers.
`gen/templates/code/cobra/gencli/command.tmpl`	Resolves flags and injects globals.
`gen/templates/code/cobra/gencli/actions.tmpl`	Corrects parameter generation.
`gen/templates/code/urfavecli/gencli/config.tmpl`	Adds urfave config resolvers.
`gen/templates/code/urfavecli/gencli/run.tmpl`	Loads config and registers globals.
`gen/templates/code/urfavecli/gencli/params.tmpl`	Adds global-flag context helpers.
`gen/templates/code/urfavecli/gencli/command.tmpl`	Resolves flags and injects globals.
`gen/templates/code/urfavecli/gencli/actions.tmpl`	Corrects parameter generation.
`gen/templates/code/yargs/gencli/config.tmpl`	Adds TypeScript config resolvers.
`gen/templates/code/yargs/gencli/run.tmpl`	Accepts argv and loads config.
`gen/templates/code/yargs/gencli/params.tmpl`	Adds global-flag accessors.
`gen/templates/code/yargs/gencli/help.tmpl`	Corrects argument help rendering.
`gen/templates/code/yargs/gencli/command.tmpl`	Resolves flags and sets globals.
`gen/cli_group_test.go`	Tests group validation.
`gen/cli_globalflags_test.go`	Tests global-flag generation.
`gen/cli_yargs_variadic_test.go`	Tests typed variadic flags.
`gen/testdata/globalflags-cli.ocs.yaml`	Defines global-flag fixture.
`gen/testdata/cobra/globalflags/gencli/run.gen.go`	Cobra global-flag golden.
`gen/testdata/cobra/globalflags/gencli/params.gen.go`	Cobra global parameter golden.
`gen/testdata/cobra/globalflags/gencli/iostreams.gen.go`	Cobra I/O golden.
`gen/testdata/cobra/globalflags/gencli/help.gen.go`	Cobra help golden.
`gen/testdata/cobra/globalflags/gencli/errors.gen.go`	Cobra error golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag.gen.go`	Cobra root-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_send.gen.go`	Cobra send-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_ping.gen.go`	Cobra ping-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_greet.gen.go`	Cobra greet-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_echo.gen.go`	Cobra echo-command golden.
`gen/testdata/cobra/globalflags/gencli/actions.gen.go`	Cobra actions golden.
`gen/testdata/cobra/gencli/run.gen.go`	Loads generated Cobra config.
`gen/testdata/cobra/gencli/cmd_petstore_user_login.gen.go`	Resolves Cobra login sources.
`gen/testdata/urfavecli/globalflags/gencli/run.gen.go`	urfave global-flag golden.
`gen/testdata/urfavecli/globalflags/gencli/params.gen.go`	urfave global parameter golden.
`gen/testdata/urfavecli/globalflags/gencli/iostreams.gen.go`	urfave I/O golden.
`gen/testdata/urfavecli/globalflags/gencli/errors.gen.go`	urfave error golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag.gen.go`	urfave root-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_send.gen.go`	urfave send-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_ping.gen.go`	urfave ping-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_greet.gen.go`	urfave greet-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_echo.gen.go`	urfave echo-command golden.
`gen/testdata/urfavecli/globalflags/gencli/actions.gen.go`	urfave actions golden.
`gen/testdata/urfavecli/gencli/run.gen.go`	Loads generated urfave config.
`gen/testdata/urfavecli/gencli/config.gen.go`	Generated urfave source resolvers.
`gen/testdata/urfavecli/gencli/cmd_petstore_user_login.gen.go`	Resolves urfave login sources.
`gen/testdata/yargs/globalflags/gencli/types.ts`	Yargs metadata golden.
`gen/testdata/yargs/globalflags/gencli/run.ts`	Yargs global option golden.
`gen/testdata/yargs/globalflags/gencli/params.ts`	Yargs global accessor golden.
`gen/testdata/yargs/globalflags/gencli/help.ts`	Yargs help golden.
`gen/testdata/yargs/globalflags/gencli/errors.ts`	Yargs error golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag.ts`	Yargs root-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-send.ts`	Yargs send-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-ping.ts`	Yargs ping-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-greet.ts`	Yargs greet-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-echo.ts`	Yargs echo-command golden.
`gen/testdata/yargs/globalflags/gencli/actions.ts`	Yargs actions golden.
`gen/testdata/yargs/gencli/run.ts`	Loads generated Yargs config.
`gen/testdata/yargs/gencli/help.ts`	Corrects generated argument help.
`gen/testdata/yargs/gencli/cmd-petstore-user-login.ts`	Resolves Yargs login sources.
`internal/cli/gencli/run.gen.go`	Loads OpenCLI configuration.
`internal/cli/gencli/cmd_ocli_gen_docs.gen.go`	Resolves docs format sources.
`internal/cli/gencli/cmd_ocli_gen_cli.gen.go`	Resolves framework sources.
`ocli.ocs.yaml`	Adds canonical self-documenting spec.
`docs/ocli.ocs.md`	Regenerates CLI documentation.
`docs/actions-implementation.md`	Documents action data access.
`README.md`	Updates canonical spec link.
`CONTRIBUTING.md`	Updates repository layout reference.
`.github/copilot-instructions.md`	Updates repository guidance.
`Makefile`	Updates generation targets and examples.
`go.mod`	Adds config-resolution dependencies.
`go.sum`	Records dependency checksums.
`examples/code/README.md`	Documents all generated examples.
`examples/code/yargs/pleasantries/src/index.ts`	Uses the new Yargs run API.
`examples/code/yargs/pleasantries/src/gencli/run.ts`	Generates the new run API.
`examples/code/yargs/pleasantries/src/gencli/help.ts`	Corrects argument help output.
`examples/code/urfavecli/pleasantries/main.go`	Adds urfave example entry point.
`examples/code/urfavecli/pleasantries/go.mod`	Defines urfave example module.
`examples/code/urfavecli/pleasantries/internal/cli/actions.go`	Implements example actions.
`examples/code/urfavecli/pleasantries/internal/gencli/run.gen.go`	Adds urfave runtime.
`examples/code/urfavecli/pleasantries/internal/gencli/params.gen.go`	Adds generated parameters.
`examples/code/urfavecli/pleasantries/internal/gencli/iostreams.gen.go`	Adds generated I/O support.
`examples/code/urfavecli/pleasantries/internal/gencli/errors.gen.go`	Adds generated errors.
`examples/code/urfavecli/pleasantries/internal/gencli/cmd_pleasantries.gen.go`	Adds generated root command.
`examples/code/urfavecli/pleasantries/internal/gencli/cmd_pleasantries_greet.gen.go`	Adds generated greet command.
`examples/code/urfavecli/pleasantries/internal/gencli/cmd_pleasantries_farewell.gen.go`	Adds generated farewell command.
`examples/code/urfavecli/pleasantries/internal/gencli/actions.gen.go`	Adds generated action interface.
`examples/code/cobra/pleasantries/internal/gencli/run.gen.go`	Adds generated Cobra runtime.
`examples/code/gencli/params.gen.go`	Removes misplaced generated fixture.
`examples/code/gencli/cmd_petstore.gen.go`	Removes misplaced root command.
`examples/code/gencli/cmd_petstore_user.gen.go`	Removes misplaced user group.
`examples/code/gencli/cmd_petstore_user_update.gen.go`	Removes misplaced update command.
`examples/code/gencli/cmd_petstore_user_logout.gen.go`	Removes misplaced logout command.
`examples/code/gencli/cmd_petstore_user_login.gen.go`	Removes misplaced login command.
`examples/code/gencli/cmd_petstore_user_get.gen.go`	Removes misplaced get command.
`examples/code/gencli/cmd_petstore_user_delete.gen.go`	Removes misplaced delete command.
`examples/code/gencli/cmd_petstore_user_createwithlist.gen.go`	Removes misplaced list-create command.
`examples/code/gencli/cmd_petstore_user_create.gen.go`	Removes misplaced create command.
`examples/code/gencli/cmd_petstore_store.gen.go`	Removes misplaced store group.
`examples/code/gencli/cmd_petstore_store_order.gen.go`	Removes misplaced order group.
`examples/code/gencli/cmd_petstore_store_order_place.gen.go`	Removes misplaced place command.
`examples/code/gencli/cmd_petstore_store_order_get.gen.go`	Removes misplaced order-get command.
`examples/code/gencli/cmd_petstore_store_order_delete.gen.go`	Removes misplaced order-delete command.
`examples/code/gencli/cmd_petstore_store_inventory.gen.go`	Removes misplaced inventory command.
`examples/code/gencli/cmd_petstore_pet.gen.go`	Removes misplaced pet group.
`examples/code/gencli/cmd_petstore_pet_uploadimage.gen.go`	Removes misplaced upload command.
`examples/code/gencli/cmd_petstore_pet_updateform.gen.go`	Removes misplaced form-update command.
`examples/code/gencli/cmd_petstore_pet_update.gen.go`	Removes misplaced pet-update command.
`examples/code/gencli/cmd_petstore_pet_get.gen.go`	Removes misplaced pet-get command.
`examples/code/gencli/cmd_petstore_pet_findbytags.gen.go`	Removes misplaced tag-search command.
`examples/code/gencli/cmd_petstore_pet_findbystatus.gen.go`	Removes misplaced status-search command.
`examples/code/gencli/cmd_petstore_pet_delete.gen.go`	Removes misplaced pet-delete command.
`examples/code/gencli/cmd_petstore_pet_add.gen.go`	Removes misplaced pet-add command.
`examples/code/gencli/cmd_petstore_list.gen.go`	Removes misplaced list command.
`examples/code/gencli/actions.gen.go`	Removes misplaced action interface.
`web/tsconfig.json`	Excludes public assets from TypeScript.
`web/src/views/GettingStarted.tsx`	Links TypeScript generation docs.
`web/src/views/GenMarkdownDocs.tsx`	Links TypeScript generation docs.
`web/src/views/GenManDocs.tsx`	Links TypeScript generation docs.
`web/src/views/GenHtmlDocs.tsx`	Links TypeScript generation docs.
`web/src/views/GeneratingGoCode.tsx`	Documents global flags and updates links.
`web/src/app/docs/code-generation-yargs/page.tsx`	Adds the Yargs documentation route.
`web/public/assets/code/actions.txt`	Adds downloadable TypeScript example.

Review details

Files reviewed: 129/136 changed files
Comments generated: 11
Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+			if f.TypeName != "" {
+				expr = fmt.Sprintf("%s(%s)", f.TypeName, expr)
+			}


+    const v = toString(altSourceValue(src));
+    if (v[1]) return v[0];
+  }
+  return undefined;


+{{- if and .IsRequired (not .AltSources)}}
          demandOption: true,
 {{- end}}


+function wasSetOnCli(names: string[]): boolean {
+  const tokens = process.argv.slice(2);
+  for (const t of tokens) {


      const cmdFlags: {{.FlagsTypeName}} = {
 {{- range .YargsFlags}}
-{{- if .TypeName}}
-        {{.FieldName}}: argv.{{.FieldName}} as {{.TypeName}},
-{{- else}}
-        {{.FieldName}}: argv.{{.FieldName}} as {{.TSType}},
-{{- end}}
+        {{.FieldName}}: {{resolveFlagValue .}},
 {{- end}}


+func toInt64(v any) (int64, bool) {
+	switch n := v.(type) {
+	case int64:
+		return n, true


 export async function run(
-  yargsInstance: yargs.Argv<{}>,
+  argv: string[],
  actions: ActionsInterface,


+              `  // Global (root-level) flags are NOT a method parameter — read them from ctx.`,
+              `  global := gencli.GlobalFlagsFromContext(ctx)`,
+              `  if global.Debug { // e.g., for a root-level --debug flag declared in your spec`,
+              `    fmt.Fprintln(a.IOStreams().Err, "debug mode enabled")`,


+	// Global flags are NOT a method parameter — read them from ctx.
+	global := gencli.GlobalFlagsFromContext(ctx)
+	if global.Debug {
+		fmt.Fprintf(a.IOStreams().Err, "sending %d message(s) to %s\n", count, recipient)


@@ -0,0 +1,40 @@
+import { ActionsInterface } from "./gencli/actions";


bcdxn added 22 commits August 14, 2026 13:16

alt sources

b6ac909

feat: urfave cli alternative sources

9caf03b

reviewed urfave impl

003b7c6

feat: enable alternative sources for cobra

bfce2d7

fix: make urfavecli load config conditional

5e6d6fb

fix: default bug

f559563

fix: examples

b74a3fc

fix: global flags and alt sources

f5ac203

fix: alt sources resolution bug in supported frameworks

24e105d

fix: flags on groups gap

14e5001

fix: variadic errors in yargs

bf0e1ee

fix: add yargs alt source capability + minor fixes

caa50cc

fix: missing yargs shorthand name when processing alt sources

8356c2d

fix: global flags missing normalization

a11e3b6

fix: bug wher toInt64 generated runtime config silently trucated float64

98a6839

fix: altSourceItems called twice in resolveSliceFlag logic

679e7bc

fix: silently dropping shorthand in yargs templates

61c7bbd

fix: minor fixes

0c8ff38

fix: handle global flags in a more elegant way

98d2624

fix: import bug + add docs

75b172d

doc: update documentation for yargs

75be0df

add docs + minor fixes

8045f76

bcdxn requested a balanced review from Copilot August 24, 2026 02:00

Copilot started reviewing on behalf of bcdxn August 24, 2026 02:01 View session

Copilot AI reviewed Aug 24, 2026

View reviewed changes

Navigation Menu

Add Code Generation Support for Alternative Sources - #19

Add Code Generation Support for Alternative Sources#19
bcdxn wants to merge 22 commits into
mainfrom
feature/alt-src-fixes

bcdxn commented Aug 24, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,40 @@
		import { ActionsInterface } from "./gencli/actions";

Conversation

bcdxn commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Alternative Sources

Global Flags

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bcdxn commented Aug 24, 2026 •

edited

Loading