argsbarg 5.1.7 → 5.1.9

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.9] - 2026-07-05
+
+### Added
+
+- **`configure --sync` config bootstrap** — creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps; Homebrew `post_install`).
+- **`_bindings` metadata** — per-key intent (`env` | `file` | `skip`) in config file; wizard persists env/skip choices; `configure set --from-env`.
+- **`ctx.appConfig` unsafe I/O** — `getUnsafe`, `setUnsafe`, `readUnsafe` for raw file access (works without `program.appConfig`).
+
+### Changed
+
+- **App config detection** — `appConfigInstalled` / `--status` use file existence only (not directory-only).
+- **Configure wizard** — skips addressed keys; Enter at env prompt persists `_bindings`; accurate write messaging.
+- **`configure --status`** — binding hints on required keys (`set (env)`, etc.).
+- **Partial config validation** — single-key / bindings-only writes skip required-property checks.
+- biome lineLength=120
+
+## [5.1.8] - 2026-07-05
+
+
 ## [5.1.7] - 2026-07-05
 
 ### Changed
@@ -627,7 +646,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.7...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.9...HEAD
+[5.1.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.9
+[5.1.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.8
 [5.1.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.7
 [5.1.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.6
 [5.1.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.5

package/docs/cli-program.md

@@ -432,7 +432,9 @@ await cli.run();
 
 See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.md) (`configure.targets`), and [mcp.md](mcp.md).
 
-**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` in handlers; env export remains for subprocess inheritance. `path` is the resolved absolute config file path (`~/.local/lib/<key>/config`); `dir` is its parent directory.
+**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read` (schema-aware, resolved values); `getUnsafe`, `setUnsafe`, `readUnsafe` (raw file, works without `program.appConfig`); `path`, `dir`. Prefer `get`/`set` when `appConfig` is declared. Env export remains for subprocess inheritance. `path` is `~/.local/lib/<key>/config.json`; `dir` is its parent.
+
+**`_bindings`:** reserved metadata for per-key intent (`env`, `file`, `skip`). Set by the wizard, `configure set --from-env`, or `ctx.appConfig.set`. Does not change resolve order (env still wins when set).
 
 ## Reserved names
 

package/docs/config-schema.md

@@ -42,11 +42,13 @@ await cli.run();
 | Interactive `configure` / `--status` | Auto-runs config wizard when `entries` is non-empty; `--status` for read-only inventory |
 | Built-in `configure get` / `configure set` | Read/write resolved values (opt-out via `commands: false`) |
 | MCP bundle / Claude plugin | `userConfig` for entries with `env` set |
-| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` |
+| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `getUnsafe`, `setUnsafe`, `readUnsafe`, `path`, `dir` — prefer `get`/`set` when `appConfig` is set |
 
-**Validation at runtime** — argsbarg validates the config file and `config set` / `ctx.appConfig.set` against the effective JSON Schema (block `jsonSchema` or synthesized all-string schema).
+**Handler access** — with `program.appConfig`: `get` / `set` / `require` use schema validation and resolved values. `getUnsafe` / `setUnsafe` / `readUnsafe` read and write the raw file (for `_bindings` and ad-hoc keys). Without `program.appConfig`, only `path`, `dir`, and the `*Unsafe` methods work.
 
-**No public config I/O exports** — consumers use `program.appConfig` for authoring and `ctx.appConfig` in handlers.
+**`_bindings`** — reserved top-level metadata: `{ "_bindings": { "apiToken": "env" } }`. Set via wizard (Enter to use env), `configure set --from-env`, or `ctx.appConfig.set` (marks `file`). Optional keys can be bound to `skip`.
+
+**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema. Partial writes (bindings only, single-key updates) skip required-property checks.
 
 See [cli-program.md — Configuration](cli-program.md#configuration-programappconfig) for resolution order, bootstrap timing, and `configure get`/`set`.
 

package/docs/configure.md

@@ -54,7 +54,7 @@ Dev flow matches release: formula `install` copies the binary and generates comp
 
 # Read or write app config (non-interactive; when program.appConfig is set)
 <key> configure get [key] [--json] [--pretty]
-<key> configure set <key> <value> [--json]
+<key> configure set <key> <value> [--json] [--from-env]
 ```
 
 Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remove-all`**, **`--remove-config`**) — see [Confirmation](#confirmation).
@@ -69,14 +69,14 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 | Claude skill | Y/n prompt | `~/.claude/skills/<dir>/` when `~/.claude` exists |
 | Codex / OpenCode / OpenClaw skills | Y/n prompt | Agent-specific dirs when available |
 | MCP config | Y/n prompt when `mcpServer.enabled` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
-| App config | auto-runs wizard | Interactive wizard writes `~/.local/lib/<key>/config.json` (schema-aware: comma-separated or JSON for primitive arrays) |
+| App config | auto-runs wizard | Interactive wizard may update `~/.local/lib/<key>/config.json` when values change; `--sync` bootstraps an empty file on install |
 
 ### Externally managed binary (Homebrew)
 
 When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
 
 - **`configure --status`** shows `app: system (PATH)`
-- **`--sync`** refreshes skills and MCP only — not the binary or completions
+- **`--sync`** refreshes skills and MCP; also creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps)
 
 MCP config uses the command name on **`PATH`**, not a Cellar path.
 
@@ -110,13 +110,19 @@ Artifact keys: `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`,
 
 ## App config (`program.appConfig`)
 
-When `program.appConfig` is set, ArgsBarg manages a flat JSON config file at `~/.local/lib/<sanitized-key>/config.json`.
+Every app gets `~/.local/lib/<sanitized-key>/config.json` on first **`configure --sync`** (Homebrew `post_install`), even without `program.appConfig`.
+
+When `program.appConfig` is set, ArgsBarg manages schema-driven values in that file.
 
 | Mode | Description |
 | --- | --- |
-| Interactive `configure` | Config wizard when you accept the configure target |
-| `--status` | Shows config path and which required keys are set or missing |
+| `configure --sync` | Bootstraps `config.json` as `{}` when missing |
+| Interactive `configure` | Config wizard when `entries` is non-empty; writes only when values or `_bindings` change |
+| `--status` | Shows config path, required keys (`set` / `missing`), and binding hints (`env`, `file`, `skip`) |
 | `--remove-config --yes` | Removes the config directory |
+| `configure set --from-env` | Bind a key to its mapped env var (stores `_bindings`, no literal secret) |
+
+Per-key intent is stored under the reserved `_bindings` object (e.g. `"apiToken": "env"`). Env still wins at resolve time when set; bindings record user choice and suppress re-prompts.
 
 Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 
@@ -127,7 +133,7 @@ Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 | Flag | Description |
 | --- | --- |
 | `--status` | Read-only inventory |
-| `--sync` | Refresh installed agent artifacts (Homebrew `post_install`; greenfield → full sync plan) |
+| `--sync` | Refresh installed agent artifacts; bootstrap `config.json` when missing (Homebrew `post_install`; greenfield → full sync plan) |
 | `--remove-all` | Remove all detected agent artifacts |
 | `--remove-config` | Remove app config directory only |
 

package/docs/distribution-homebrew.md

@@ -8,7 +8,8 @@ Argsbarg apps distribute the **binary and shell completions** through Homebrew,
 | --- | --- |
 | Binary + completions | Formula `install` block |
 | Skills + MCP | Formula `post_install` → `{key} configure --sync --yes` |
-| App config | User opt-in: `{key} configure` (interactive; not run from formula `post_install`) |
+| App config file | Bootstrapped as `{}` on `post_install` via `--sync` (`~/.local/lib/<key>/config.json`) |
+| App config values | User opt-in: `{key} configure` (interactive wizard when `program.appConfig` has entries) |
 | App config cleanup | Formula `uninstall` → `{key} configure --remove-config --yes` |
 
 **Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
@@ -89,7 +90,7 @@ Local dev formulae (`just install-local`) use a plain `file://` URL and do not n
 
 Completions require users to configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
-**Why configure is separate from `post_install`:** the wizard is interactive (TTY + prompts for secrets). Formula `post_install` runs non-interactively during `brew install` and in CI (`brew test`). Apps with `appConfig` print a one-line configure hint in formula `caveats` instead.
+**Why the wizard is separate from `post_install`:** prompting for secrets requires a TTY. `post_install` only bootstraps an empty `config.json` and refreshes skills/MCP. Apps with `appConfig` print a one-line configure hint in formula `caveats` for the interactive wizard.
 
 **MCP hosts:** when `mcpServer.enabled` is true, add a caveats line that chat apps (Cursor, Claude Desktop, etc.) must be **restarted** after `brew install` / `brew upgrade` — `post_install` updates MCP config on disk, but hosts typically load it only at startup.
 

package/examples/full-example/justfile

@@ -20,10 +20,8 @@ build:
     @rm -f .*.bun-build
 
 # Run schemagen, git diff check, typecheck, and format
-check: schemagen
+check: schemagen format typecheck
     git diff --exit-code schemas/
-    just typecheck
-    just format
 
 # Run the CLI from source with optional args; restarts on file changes
 dev *ARGS:
@@ -38,7 +36,7 @@ alias fmt := format
 
 # Format and lint sources (auto-fix)
 format:
-    bun run biome check ./src ./scripts --write
+    bun run biome check ./src ./scripts --write --unsafe
 
 # Alias for backward compatibility
 install: install-local
@@ -81,7 +79,6 @@ run *ARGS:
 # Generate JSON Schema artifacts from TypeScript types
 schemagen:
     bun run schemagen
-    just format
 
 # Install bun/npm dependencies
 setup:

package/examples/full-example/scripts/with-dev-formula.ts

@@ -50,6 +50,11 @@ if (sep === -1 || sep === process.argv.length - 1) {
 }
 
 const cmd = process.argv.slice(sep + 1);
+const executable = cmd[0];
+if (!executable) {
+  process.stderr.write("Usage: bun scripts/with-dev-formula.ts -- <command...>\n");
+  process.exit(1);
+}
 let restored = false;
 
 function restore(): void {
@@ -63,7 +68,7 @@ function restore(): void {
 try {
   backupReleaseFormula();
   writeDevFormula();
-  const result = spawnSync(cmd[0], cmd.slice(1), { stdio: "inherit" });
+  const result = spawnSync(executable, cmd.slice(1), { stdio: "inherit" });
   process.exitCode = result.status === null ? 1 : result.status;
 } finally {
   restore();

package/index.d.ts

@@ -7,11 +7,15 @@ export declare function displayAppConfigPath(program: CliProgram): string;
 export type ResolvedConfig = Record<string, unknown>;
 declare class EmptyAppConfigSnapshot {
 	private readonly program;
-	constructor(program: CliProgram);
+	private fileData;
+	constructor(program: CliProgram, fileData?: Record<string, unknown>);
 	get(_key: string): undefined;
 	require(key: string): never;
 	set(_key: string, _value: unknown): void;
 	read(): ResolvedConfig;
+	readUnsafe(): Record<string, unknown>;
+	getUnsafe(key: string): unknown;
+	setUnsafe(key: string, value: unknown): void;
 	/** Resolved absolute path to the app JSON config file (OS default from `program.key`). */
 	get path(): string;
 	/** Resolved absolute directory containing the config file. */
@@ -26,13 +30,18 @@ declare class AppConfigSnapshot {
 	require(key: string): unknown;
 	set(key: string, value: unknown): void;
 	read(): ResolvedConfig;
+	readUnsafe(): Record<string, unknown>;
+	getUnsafe(key: string): unknown;
+	setUnsafe(key: string, value: unknown): void;
 	/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
 	get path(): string;
 	/** Resolved absolute directory containing the config file. */
 	get dir(): string;
 	/** Replace snapshot after external bootstrap (internal). */
 	refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void;
+	private persistFileData;
 	private assertEntryKey;
+	private assertUnsafeKey;
 }
 export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
 /** Coerced leaf inputs keyed by option and positional names. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.1.7",
+  "version": "5.1.9",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/builtins.test.ts

@@ -52,9 +52,7 @@ describe("builtins help copy", () => {
 
   test("configure copy omits MCP when mcpServer unset", () => {
     const caps = resolveCapabilities(noMcp);
-    expect(configureCommandDescription(noMcp, caps)).toBe(
-      "Set up agent skills for this app (binary via Homebrew).",
-    );
+    expect(configureCommandDescription(noMcp, caps)).toBe("Set up agent skills for this app (binary via Homebrew).");
     expect(configureCommandDescription(noMcp, caps)).not.toContain("MCP");
     expect(configureSyncOptionDescription(noMcp, caps)).not.toContain("MCP");
     const configure = cliBuiltinConfigureCommand(noMcp);

package/src/builtins/completion-bash.ts

@@ -1,13 +1,7 @@
 import { CliOptionKind, type CliRouter } from "../types.ts";
 import { emitConsumeLong, emitConsumeShort, emitMatchChild } from "./completion-simulate-shared.ts";
 import { collectScopes, type ScopeRec } from "./scopes.ts";
-import {
-  escShellSingleQuoted,
-  identToken,
-  kHelpLong,
-  kHelpShort,
-  mainName,
-} from "./shell-helpers.ts";
+import { escShellSingleQuoted, identToken, kHelpLong, kHelpShort, mainName } from "./shell-helpers.ts";
 
 function emitSimulate(ident: string): string {
   let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
@@ -18,10 +12,7 @@ function emitSimulate(ident: string): string {
   o += "      ((i++)); continue\n";
   o += "    fi\n";
   o += "    if [[ $w == --* ]]; then\n";
-  o += '      steps=$(_${ident}_nac_consume_long "$sid" "$w" "${COMP_WORDS[i+1]}")\n'.replace(
-    "${ident}",
-    ident,
-  );
+  o += '      steps=$(_${ident}_nac_consume_long "$sid" "$w" "${COMP_WORDS[i+1]}")\n'.replace("${ident}", ident);
   o += "      case $steps in\n";
   o += "        0) break ;;\n";
   o += "        1) ((i++)) ;;\n";
@@ -54,20 +45,13 @@ function emitEnumReplyBash(ident: string, scopes: ScopeRec[]): string {
   o += '  local sid="$1" prev="$2" cur="$3"\n';
   o += "  case $sid in\n";
   for (const [i, sc] of scopes.entries()) {
-    const enumOpts = sc.opts.filter(
-      (op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0,
-    );
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
     if (enumOpts.length === 0) continue;
     o += `    ${i})\n`;
     o += "      case $prev in\n";
     for (const op of enumOpts) {
       const words = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
-      o +=
-        "        --" +
-        op.name +
-        ") COMPREPLY=( $(compgen -W '" +
-        words +
-        '\' -- "$cur") ); return 0 ;;\n';
+      o += `        --${op.name}) COMPREPLY=( $(compgen -W '${words}' -- "$cur") ); return 0 ;;\n`;
     }
     o += "      esac\n";
     o += "      ;;\n";
@@ -85,10 +69,7 @@ function emitMainBodyBash(schema: CliRouter, ident: string): string {
   o += '  local prev="${COMP_WORDS[COMP_CWORD-1]:-}"\n';
   o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
   o += "  local sid=$REPLY_SID\n";
-  o += '  if _${ident}_nac_enum_reply "$sid" "$prev" "$cur"; then return; fi\n'.replace(
-    "${ident}",
-    ident,
-  );
+  o += '  if _${ident}_nac_enum_reply "$sid" "$prev" "$cur"; then return; fi\n'.replace("${ident}", ident);
   o += "  if [[ $cur == -* ]]; then\n";
   o += '    local oname="A_${ident}_${sid}_opts"\n'.replace("${ident}", ident);
   o += "    local -a optsarr\n";
@@ -111,9 +92,7 @@ function emitMainBodyBash(schema: CliRouter, ident: string): string {
   o += "    fi\n";
   o += "  fi\n";
   o += "}\n\n";
-  o += "complete -F _${main} ${schema.key}\n"
-    .replace("${main}", main)
-    .replace("${schema.key}", schema.key);
+  o += "complete -F _${main} ${schema.key}\n".replace("${main}", main).replace("${schema.key}", schema.key);
   return o;
 }
 

package/src/builtins/completion-group.ts

@@ -45,7 +45,6 @@ export function cliBuiltinCompletionGroup(program: CliProgram): import("../types
     ],
   };
   router.notes =
-    "Completions are installed by Homebrew during formula install.\n\n" +
-    "See: https://docs.brew.sh/Shell-Completion";
+    "Completions are installed by Homebrew during formula install.\n\n" + "See: https://docs.brew.sh/Shell-Completion";
   return router;
 }

package/src/builtins/completion-simulate-shared.ts

@@ -44,11 +44,7 @@ export function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
 }
 
 /** Emits `_<ident>_nac_consume_short`; dialect selects substring syntax. */
-export function emitConsumeShort(
-  ident: string,
-  scopes: ScopeRec[],
-  dialect: CompletionShellDialect,
-): string {
+export function emitConsumeShort(ident: string, scopes: ScopeRec[], dialect: CompletionShellDialect): string {
   const firstChar = dialect === "bash" ? "ch=${rest:0:1}" : "ch=${rest[1,1]}";
   const restAdvance = dialect === "bash" ? "rest=${rest:1}" : "rest=${rest[2,-1]}";
 
@@ -93,11 +89,7 @@ export function emitConsumeShort(
 }
 
 /** Emits `_<ident>_nac_match_child` — identical for bash and zsh. */
-export function emitMatchChild(
-  ident: string,
-  scopes: ScopeRec[],
-  pathIndex: Record<string, number>,
-): string {
+export function emitMatchChild(ident: string, scopes: ScopeRec[], pathIndex: Record<string, number>): string {
   let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
   o += '  local sid="$1" w="$2"\n';
   o += "  case $sid in\n";

package/src/builtins/completion-zsh.ts

@@ -1,13 +1,7 @@
 import { CliOptionKind, type CliRouter } from "../types.ts";
 import { emitConsumeLong, emitConsumeShort, emitMatchChild } from "./completion-simulate-shared.ts";
 import { collectScopes, type ScopeRec } from "./scopes.ts";
-import {
-  escShellSingleQuoted,
-  identToken,
-  kHelpLong,
-  kHelpShort,
-  mainName,
-} from "./shell-helpers.ts";
+import { escShellSingleQuoted, identToken, kHelpLong, kHelpShort, mainName } from "./shell-helpers.ts";
 
 function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
   let out = "";
@@ -25,19 +19,9 @@ function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
       escShellSingleQuoted("Show help for this command.") +
       "'";
     for (const o of sc.opts) {
-      out +=
-        " '" +
-        escShellSingleQuoted(`--${o.name}`) +
-        ":" +
-        escShellSingleQuoted(o.description) +
-        "'";
+      out += ` '${escShellSingleQuoted(`--${o.name}`)}:${escShellSingleQuoted(o.description)}'`;
       if (o.shortName) {
-        out +=
-          " '" +
-          escShellSingleQuoted(`-${o.shortName}`) +
-          ":" +
-          escShellSingleQuoted(o.description) +
-          "'";
+        out += ` '${escShellSingleQuoted(`-${o.shortName}`)}:${escShellSingleQuoted(o.description)}'`;
       }
     }
     out += ")\n";
@@ -63,10 +47,7 @@ function emitSimulateZsh(ident: string): string {
   o += "      ((i++)); continue\n";
   o += "    fi\n";
   o += "    if [[ $w == --* ]]; then\n";
-  o += '      steps=$(_${ident}_nac_consume_long "$sid" "$w" "${words[i+1]}")\n'.replace(
-    "${ident}",
-    ident,
-  );
+  o += '      steps=$(_${ident}_nac_consume_long "$sid" "$w" "${words[i+1]}")\n'.replace("${ident}", ident);
   o += "      case $steps in\n";
   o += "        0) break ;;\n";
   o += "        1) ((i++)) ;;\n";
@@ -99,9 +80,7 @@ function emitEnumReplyZsh(ident: string, scopes: ScopeRec[]): string {
   o += "  local sid=$1 prev=$2\n";
   o += "  case $sid in\n";
   for (const [i, sc] of scopes.entries()) {
-    const enumOpts = sc.opts.filter(
-      (op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0,
-    );
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
     if (enumOpts.length === 0) continue;
     o += `    ${i})\n`;
     o += "      case $prev in\n";
@@ -124,10 +103,7 @@ function emitMainBodyZsh(schema: CliRouter, ident: string): string {
   o += '  local curcontext="$curcontext" ret=1\n';
   o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
   o += "  local sid=$REPLY_SID\n";
-  o += '  if _${ident}_nac_enum_reply "$sid" "$words[CURRENT-1]"; then return 0; fi\n'.replace(
-    "${ident}",
-    ident,
-  );
+  o += '  if _${ident}_nac_enum_reply "$sid" "$words[CURRENT-1]"; then return 0; fi\n'.replace("${ident}", ident);
   o += "  if [[ $PREFIX == -* ]]; then\n";
   o += "    local -a optsarr\n";
   o += '    local oname="A_${ident}_${sid}_opts"\n'.replace("${ident}", ident);
@@ -149,9 +125,7 @@ function emitMainBodyZsh(schema: CliRouter, ident: string): string {
   o += "  fi\n";
   o += "  return ret\n";
   o += "}\n\n";
-  o += "compdef _${main} ${schema.key}\n"
-    .replace("${main}", main)
-    .replace("${schema.key}", schema.key);
+  o += "compdef _${main} ${schema.key}\n".replace("${main}", main).replace("${schema.key}", schema.key);
   return o;
 }
 

package/src/builtins/config.test.ts

@@ -6,6 +6,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { readBindings } from "../config/bindings.ts";
 import { resolveAppConfigPath, writeAppConfigFile } from "../config/file.ts";
 import { Cli, type CliProgram } from "../index.ts";
 
@@ -93,4 +94,31 @@ describe("builtins/config", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  test("config set --from-env stores binding without literal", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-from-env-"));
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
+    const prev = process.env.API_TOKEN;
+    process.env.API_TOKEN = "from-env";
+    try {
+      const program = configFixture();
+      writeAppConfigFile(program, { apiToken: "seed" }, { partial: true });
+      const result = await new Cli(program).invoke(["configure", "set", "apiToken", "--from-env"]);
+      expect(result.exitCode).toBe(0);
+      const raw = await new Cli(program).invoke(["configure", "get", "apiToken"]);
+      expect(raw.stdout.trim()).toBe("REDACTED");
+      const configPath = resolveAppConfigPath(program);
+      const { readFileSync } = await import("node:fs");
+      const onDisk = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>;
+      expect(onDisk.apiToken).toBeUndefined();
+      expect(readBindings(onDisk).apiToken).toBe("env");
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/src/builtins/config.ts

@@ -2,6 +2,7 @@
 Built-in `configure get` / `configure set` subcommands.
 */
 
+import { clearFileValue, setBinding } from "../config/bindings.ts";
 import { bootstrapAppConfig } from "../config/bootstrap.ts";
 import {
   configCommandsEnabled,
@@ -28,12 +29,7 @@ const PRETTY_OPTION: CliOption = {
   kind: CliOptionKind.Presence,
 };
 
-function configGetOutput(
-  program: CliProgram,
-  key: string | undefined,
-  json: boolean,
-  pretty: boolean,
-): void {
+function configGetOutput(program: CliProgram, key: string | undefined, json: boolean, pretty: boolean): void {
   const appConfig = program.appConfig;
   if (!appConfig) {
     return;
@@ -106,6 +102,31 @@ function configGetOutput(
   }
 }
 
+const FROM_ENV_OPTION: CliOption = {
+  name: "from-env",
+  description: "Bind this key to its mapped environment variable (no literal value stored).",
+  kind: CliOptionKind.Presence,
+};
+
+function configSetFromEnv(program: CliProgram, key: string): void {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return;
+  }
+  const entry = appConfig.entries[key];
+  if (!entry?.env) {
+    process.stderr.write(`Configuration key '${key}' has no env mapping for --from-env.\n`);
+    process.exit(1);
+  }
+  const hostEnv = captureMappedHostEnv(program);
+  const { fileData } = bootstrapAppConfig(program, { validateFile: true });
+  let next = clearFileValue(fileData, key);
+  next = setBinding(next, key, "env");
+  writeAppConfigFile(program, next, { partial: true });
+  const resolved = resolveAppConfig(program, next, hostEnv);
+  exportConfigToEnv(program, resolved, hostEnv);
+}
+
 function configSetRun(program: CliProgram, key: string, rawValue: string, useJson: boolean): void {
   const appConfig = program.appConfig;
   if (!appConfig) {
@@ -135,8 +156,8 @@ function configSetRun(program: CliProgram, key: string, rawValue: string, useJso
 
   const hostEnv = captureMappedHostEnv(program);
   const { fileData } = bootstrapAppConfig(program, { validateFile: true });
-  const next = { ...fileData, [key]: parsed };
-  writeAppConfigFile(program, next);
+  const next = setBinding({ ...fileData, [key]: parsed }, key, "file");
+  writeAppConfigFile(program, next, { partial: true });
   const resolved = resolveAppConfig(program, next, hostEnv);
   exportConfigToEnv(program, resolved, hostEnv);
 }
@@ -166,7 +187,7 @@ function configSetLeaf(program: CliProgram, mcpSetEnabled: boolean): CliLeaf {
   return {
     key: "set",
     description: "Write one configuration key to the config file.",
-    options: [JSON_OPTION],
+    options: [JSON_OPTION, FROM_ENV_OPTION],
     mcpTool: mcpSetEnabled ? undefined : { enabled: false },
     positionals: [
       {
@@ -191,10 +212,19 @@ function configSetLeaf(program: CliProgram, mcpSetEnabled: boolean): CliLeaf {
         process.stderr.write("configure set requires a key.\n");
         process.exit(1);
       }
+      if (ctx.hasFlag("from-env")) {
+        const raw = ctx.args[1];
+        if (raw !== undefined && raw.length > 0) {
+          process.stderr.write("configure set --from-env does not accept a value.\n");
+          process.exit(1);
+        }
+        configSetFromEnv(program, key);
+        return;
+      }
       const raw = ctx.args[1];
       if (raw === undefined || raw.length === 0) {
         if (!ctx.hasFlag("json")) {
-          process.stderr.write("configure set requires a value (or --json).\n");
+          process.stderr.write("configure set requires a value (or --from-env).\n");
           process.exit(1);
         }
         process.stderr.write("configure set requires a value.\n");

package/src/builtins/configure-copy.ts

@@ -20,7 +20,7 @@ function enabledKinds(program: CliProgram, caps: CliCapabilities): Kind[] {
 
 function joinEnglish(items: string[]): string {
   if (items.length === 0) return "agent artifacts";
-  if (items.length === 1) return items[0]!;
+  if (items.length === 1) return items[0] ?? "agent artifacts";
   if (items.length === 2) return `${items[0]} and ${items[1]}`;
   return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
 }
@@ -41,7 +41,7 @@ export function configureSyncOptionDescription(program: CliProgram, caps: CliCap
   return `Refresh installed ${short(program, caps)}. Used by Homebrew post_install.`;
 }
 
-export function docsSkillTopicDescription(program: CliProgram, caps: CliCapabilities): string {
+export function docsSkillTopicDescription(_program: CliProgram, caps: CliCapabilities): string {
   if (caps.configure) {
     return "Print a reference agent SKILL; run `configure` to install an optimized copy.";
   }
@@ -78,9 +78,6 @@ export function configureCommandNotes(program: CliProgram, _caps: CliCapabilitie
   if (program.appConfig) {
     lines.push("Remove app config only:", `  ${app} configure --remove-config --yes`, "");
   }
-  lines.push(
-    "Use --dry to preview changes without writing files.",
-    "Use --json for machine-readable output.",
-  );
+  lines.push("Use --dry to preview changes without writing files.", "Use --json for machine-readable output.");
   return lines.join("\n");
 }

package/src/builtins/dispatch.ts

@@ -11,11 +11,7 @@ import { completionBashScript } from "./completion-bash.ts";
 import { completionFishScript } from "./completion-fish.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
 import { completionZshScript } from "./completion-zsh.ts";
-import {
-  CONFIGURE_RUN_KEY,
-  cliBuiltinConfigureCommand,
-  isConfigureConfigPath,
-} from "./configure.ts";
+import { CONFIGURE_RUN_KEY, cliBuiltinConfigureCommand, isConfigureConfigPath } from "./configure.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliPresentationRoot } from "./presentation.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
@@ -35,11 +31,7 @@ function completionSchema(program: CliProgram, opts: DispatchBuiltinOpts): CliRo
 /**
  * Handles built-in commands after parse.
  */
-export async function dispatchBuiltin(
-  program: CliProgram,
-  pr: ParseResult,
-  opts: DispatchBuiltinOpts,
-): Promise<void> {
+export async function dispatchBuiltin(program: CliProgram, pr: ParseResult, opts: DispatchBuiltinOpts): Promise<void> {
   if (pr.kind !== ParseKind.Ok) {
     return;
   }

package/src/builtins/export.ts

@@ -41,9 +41,7 @@ function exportBuiltinNode(cmd: CliNode): CliSchemaExport | null {
     if (cmd.fallbackMode !== undefined) {
       out.fallbackMode = cmd.fallbackMode;
     }
-    const children = cmd.commands
-      .map((ch) => exportBuiltinNode(ch))
-      .filter((ch): ch is CliSchemaExport => ch !== null);
+    const children = cmd.commands.map((ch) => exportBuiltinNode(ch)).filter((ch): ch is CliSchemaExport => ch !== null);
     if (children.length > 0) {
       out.commands = children;
     }