gunshi-c12

Thin Gunshi plugin over c12.

gunshi-c12 does not re-implement config loading. It wires Gunshi global options into direct c12 calls (loadConfig/watchConfig) and exposes them on ctx.extensions.c12.

Install

pnpm add gunshi-c12

Quick Start

import { cli, define } from "gunshi";
import { c12 } from "gunshi-c12";

const command = define({
  name: "build",
  run: async (ctx) => {
    const configApi = ctx.extensions.c12;
    const { config } = await configApi.loadConfig();
    console.log(config);
  },
});

await cli(process.argv.slice(2), command, {
  name: "my-cli",
  version: "1.0.0",
  plugins: [c12({ name: "myapp" })],
});

What This Plugin Adds

• Registers Gunshi global options:
  • default mode: --config, --env
  • scoped mode (configName): --config-<name>, --env-<name>
• Resolves APPNAME overrides in scoped mode:
  • configName: "app" reads APP_APPNAME
• Merges options and calls c12 directly.

Everything else (file formats, layering, extends, dotenv, watch behavior, etc.) is c12 behavior.

Option Merge Rules

The extension merges options in this order:

1. Plugin options passed to c12(...)
2. CLI-derived overrides from global flags (config*/env*)
3. Runtime options passed to loadConfig(...) or watchConfig(...)

For nested overrides, merge is shallow by key (last write wins per key).

Resolved c12 name priority:

1. options.name passed to c12(...)
2. In scoped mode, APP_APPNAME-style override (<CONFIGNAME>_APPNAME) then configName
3. Gunshi program name (ctx.env.name, usually CLI name)
4. Fallback: "config"

Scoped Configuration (configName)

Use configName when you want config flags scoped to a domain.

import { c12 } from "gunshi-c12";

// Adds --config-app and --env-app
const plugin = c12({ configName: "app", name: "myapp" });

configName also enables APPNAME override lookup:

# Uses APP_APPNAME to override resolved c12 name
APP_APPNAME=project-a my-cli build --config-app ./app.config.ts

API

c12(options?)

Creates the Gunshi plugin.

• options is c12 LoadConfigOptions plus:
  • configName?: string

Extension Methods

From ctx.extensions.c12:

• loadConfig(options?) -> forwards to c12.loadConfig
• watchConfig(options?) -> forwards to c12.watchConfig
• load(options?) -> alias of loadConfig

Types

This package re-exports core c12 types (for example LoadConfigOptions, WatchConfigOptions, ResolvedConfig, ConfigWatcher) and plugin types (C12Extension, ConfigLoader).

License

MIT