feat: drop `-e` short alias for `--example` by yamcodes · Pull Request #1370 · yamcodes/arkenv

yamcodes · 2026-07-17T19:04:27Z

Drops the -e short alias for --example, making --example long-form only. -e is permanently reserved so it stays free for a possible future --env / --environment option.

Why

Across the CLI ecosystem (Docker, Kubernetes, Unix), -e almost universally means --env / --environment. AI agents instinctively reach for arkenv init -e NODE_ENV=production, which silently bound to the unrelated --example flag and consumed the next token — producing behavior that didn't match intent and triggering retry/hallucination loops.

Changes

packages/cli/src/cli/cli.ts: drop the -e short alias from the --example flag config (kept as value kind, long-form only). Added a comment marking -e as reserved. Removal flows automatically through knownFlags, valuedFlags, bundled-short-flag expansion, and the example accessor.
packages/cli/src/cli/commands/help.ts: help output shows --example with no short alias.
apps/www/content/docs/cli/index.mdx: flags table no longer lists -e for --example.
Tests updated: assertions that -e maps to --example are removed/replaced (value-flag coverage repurposed to -H/--example); new coverage asserts -e and -ye are rejected as Unknown argument: -e while --example still works.
Changeset: @arkenv/cli minor, documented as a BREAKING CHANGE (mirrors the -C/-a removal precedent).

Behavior

arkenv init --example <name> works exactly as before.
arkenv init -e <name> → Unknown argument: -e.
-ye (bundled) → Unknown argument: -e.

Follow-up

After merge to dev, run /forward-port to bring this to the v1 branch (packages/cli/src/** → packages/arkenv/src/**, changeset key @arkenv/cli → arkenv).

Made with Cursor

Co-authored-by: Cursor <cursoragent@cursor.com>

changeset-bot · 2026-07-17T19:04:38Z

🦋 Changeset detected

Latest commit: 1b42f74

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@arkenv/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-07-17T19:05:37Z

Open in StackBlitz

arkenv

npm i https://pkg.pr.new/arkenv@1370

@arkenv/build

npm i https://pkg.pr.new/@arkenv/build@1370

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@1370

@arkenv/cli

npm i https://pkg.pr.new/@arkenv/cli@1370

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@1370

@arkenv/nextjs

npm i https://pkg.pr.new/@arkenv/nextjs@1370

@arkenv/nuxt

npm i https://pkg.pr.new/@arkenv/nuxt@1370

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@1370

commit: 1b42f74

arkenv-bot · 2026-07-17T19:05:43Z

📦 Bundle Size Report

No results found

✅ All size limits passed!

pullfrog

✅ No new issues found.

Reviewed changes — drops the -e short alias for arkenv init --example and updates tests, help text, docs, and the changeset.

packages/cli/src/cli/cli.ts — removes -e from the --example flag config and adds a comment reserving -e for a possible future --env / --environment option.
packages/cli/src/cli/commands/help.ts and apps/www/content/docs/cli/index.mdx — no longer list -e as an alias for --example.
packages/cli/src/cli/cli.test.ts and packages/cli/src/cli/commands/help.test.ts — repurpose value-flag coverage to -H / --example and add assertions that -e and -ye are rejected as unknown arguments.
.changeset/drop-example-e-alias.md — documents the breaking change and provides a migration snippet.

Local validation: pnpm --filter @arkenv/cli exec vitest run src/cli/cli.test.ts src/cli/commands/help.test.ts (30 tests passed) and pnpm --filter @arkenv/cli run typecheck both pass.

^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

arkenv-bot · 2026-07-17T19:08:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (Asia/Almaty)
arkenv	Ready	Preview, Comment	Jul 18 2026, 12:08 AM (Asia/Almaty)

(#1378) Forward-ports the `-e` short-alias removal from dev PR #1370 (issue #1367) onto the `v1` branch, re-implemented at the v1 package layout (`packages/arkenv/src/**`, package `arkenv`). ## Summary Drops the `-e` short alias for `init --example`, making `--example` **long-form only**. `-e` is permanently reserved so it stays free for a possible future `--env` / `--environment` option. Across the CLI ecosystem (Docker, Kubernetes, Unix), `-e` almost universally means `--env` / `--environment`. AI agents instinctively reach for `arkenv init -e NODE_ENV=production`, which silently bound to the unrelated `--example` flag and consumed the next token — behavior that didn't match intent and triggered retry/hallucination loops. ## Changes - `packages/arkenv/src/cli/cli.ts`: drop the `-e` short alias from the `--example` flag config (kept as `value` kind, long-form only). Added a comment marking `-e` as reserved. Removal flows automatically through `knownFlags`, `valuedFlags`, bundled-short-flag expansion, and the `example` accessor. - `packages/arkenv/src/cli/commands/help.ts`: help output shows `--example` with no short alias. - `apps/www/content/docs/cli/index.mdx`: flags table no longer lists `-e` for `--example`. - Tests updated: assertions that `-e` maps to `--example` are removed/replaced (value-flag coverage repurposed to `-H`/`--example`); new coverage asserts `-e` and `-ye` are rejected as `Unknown argument: -e` while `--example` still works. - Changeset `drop-example-e-alias.md`: `arkenv` **minor**, documented as a **BREAKING CHANGE** (mirrors the `-C`/`-a` removal precedent). ## Forward-port notes - Adapted paths: dev `packages/cli/src/**` → v1 `packages/arkenv/src/**`. - Changeset key `@arkenv/cli` → `arkenv` (v1 package name); migration snippet uses the bare `arkenv init` form to match the existing v1 `trim-short-flag-aliases` changeset. - Updated the still-unreleased v1 `trim-short-flag-aliases.md` changeset to drop `-e` from its "unchanged aliases" list, since it is no longer accurate after this change. ## Behavior - `arkenv init --example <name>` works exactly as before. - `arkenv init -e <name>` → `Unknown argument: -e`. - `-ye` (bundled) → `Unknown argument: -e`. ## Verification - `arkenv` `cli.test.ts` + `help.test.ts` pass (30 tests) with internal deps built. Remaining suite failures are pre-existing sandbox limitations (`git init` denied, smoke tests needing a built binary) and unrelated to this change. Ports #1370 · relates to #1367 Made with [Cursor](https://cursor.com) Co-authored-by: Cursor <cursoragent@cursor.com>

@yamcodes

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to dev, this PR will be updated. # Releases ## @arkenv/cli@0.5.0 ### Minor Changes - #### Drop the `-e` short alias for `init --example` _[`#1370`](#1370) [`b86b999`](b86b999) [@yamcodes](https://github.com/yamcodes)_ **BREAKING CHANGE**: The `-e` short alias is no longer recognized. Its long form, `--example`, continues to work exactly as before. Across the broader CLI ecosystem, `-e` almost universally means `--env` / `--environment`. For a type-safe environment variable library, mapping `-e` to `--example` is a sharp trap: AI agents instinctively reach for `arkenv init -e NODE_ENV=production`, which silently bound to `--example` and consumed the next token as the example name. `-e` is now permanently reserved so it stays free for a future `--env` / `--environment` option. Passing `-e` — standalone or inside a bundle like `-ye` — now fails fast with the standard `Unknown argument: -e` error. Migration: replace the short alias with its long form. ```bash # Before npx @arkenv/cli@latest init -e with-vite-react # After npx @arkenv/cli@latest init --example with-vite-react ``` ### Patch Changes - #### Improve npm keywords across published packages for discoverability _[`#1383`](#1383) [`bf60ab2`](bf60ab2) [@yamcodes](https://github.com/yamcodes)_ Clean up and extend the `keywords` field of every published package so npm search, aggregators, and LLM-powered package discovery surface ArkEnv for the terms users actually search for. - Remove the misleading `pnpm` keyword from `arkenv` and add `env`, `environment-variables`, `dotenv`, `config`, `standard-schema`, and the supported validators `zod` and `valibot`. - Deduplicate the repeated `arkenv` keyword in `@arkenv/vite-plugin`. - Give every env-related package a shared baseline (`env`, `environment-variables`, `dotenv`, `config`, `validation`, `typesafe`, `standard-schema`) alongside their integration-specific terms. - Add a keyword set to `@arkenv/fumadocs-ui`, which previously had none. - #### Add `with-valibot` to the bundled example registry and scaffold defaults _[`#1382`](#1382) [`4aa2e42`](4aa2e42) [@yamcodes](https://github.com/yamcodes)_ Register the new standalone `with-valibot` example so it is offered alongside `with-zod` when scaffolding, including in the offline fallback registry used when the remote registry fetch fails. - Add a `with-valibot` entry to the bundled fallback example registry. - Add `with-valibot` env defaults (`HOST`, `PORT`, `NODE_ENV`) to the scaffold defaults map. ## arkenv@0.12.3 ### Patch Changes - #### Improve npm keywords across published packages for discoverability _[`#1383`](#1383) [`bf60ab2`](bf60ab2) [@yamcodes](https://github.com/yamcodes)_ Clean up and extend the `keywords` field of every published package so npm search, aggregators, and LLM-powered package discovery surface ArkEnv for the terms users actually search for. - Remove the misleading `pnpm` keyword from `arkenv` and add `env`, `environment-variables`, `dotenv`, `config`, `standard-schema`, and the supported validators `zod` and `valibot`. - Deduplicate the repeated `arkenv` keyword in `@arkenv/vite-plugin`. - Give every env-related package a shared baseline (`env`, `environment-variables`, `dotenv`, `config`, `validation`, `typesafe`, `standard-schema`) alongside their integration-specific terms. - Add a keyword set to `@arkenv/fumadocs-ui`, which previously had none. ## @arkenv/bun-plugin@0.1.11 ### Patch Changes - #### Improve npm keywords across published packages for discoverability _[`#1383`](#1383) [`bf60ab2`](bf60ab2) [@yamcodes](https://github.com/yamcodes)_ Clean up and extend the `keywords` field of every published package so npm search, aggregators, and LLM-powered package discovery surface ArkEnv for the terms users actually search for. - Remove the misleading `pnpm` keyword from `arkenv` and add `env`, `environment-variables`, `dotenv`, `config`, `standard-schema`, and the supported validators `zod` and `valibot`. - Deduplicate the repeated `arkenv` keyword in `@arkenv/vite-plugin`. - Give every env-related package a shared baseline (`env`, `environment-variables`, `dotenv`, `config`, `validation`, `typesafe`, `standard-schema`) alongside their integration-specific terms. - Add a keyword set to `@arkenv/fumadocs-ui`, which previously had none. <details><summary>Updated 1 dependency</summary> [`bf60ab2`](bf60ab2) - `arkenv@0.12.3` </details> ## @arkenv/fumadocs-ui@0.0.10 ### Patch Changes - #### Improve npm keywords across published packages for discoverability _[`#1383`](#1383) [`bf60ab2`](bf60ab2) [@yamcodes](https://github.com/yamcodes)_ Clean up and extend the `keywords` field of every published package so npm search, aggregators, and LLM-powered package discovery surface ArkEnv for the terms users actually search for. - Remove the misleading `pnpm` keyword from `arkenv` and add `env`, `environment-variables`, `dotenv`, `config`, `standard-schema`, and the supported validators `zod` and `valibot`. - Deduplicate the repeated `arkenv` keyword in `@arkenv/vite-plugin`. - Give every env-related package a shared baseline (`env`, `environment-variables`, `dotenv`, `config`, `validation`, `typesafe`, `standard-schema`) alongside their integration-specific terms. - Add a keyword set to `@arkenv/fumadocs-ui`, which previously had none. ## @arkenv/nextjs@0.1.4 ### Patch Changes - #### Improve npm keywords across published packages for discoverability _[`#1383`](#1383) [`bf60ab2`](bf60ab2) [@yamcodes](https://github.com/yamcodes)_ Clean up and extend the `keywords` field of every published package so npm search, aggregators, and LLM-powered package discovery surface ArkEnv for the terms users actually search for. - Remove the misleading `pnpm` keyword from `arkenv` and add `env`, `environment-variables`, `dotenv`, `config`, `standard-schema`, and the supported validators `zod` and `valibot`. - Deduplicate the repeated `arkenv` keyword in `@arkenv/vite-plugin`. - Give every env-related package a shared baseline (`env`, `environment-variables`, `dotenv`, `config`, `validation`, `typesafe`, `standard-schema`) alongside their integration-specific terms. - Add a keyword set to `@arkenv/fumadocs-ui`, which previously had none. <details><summary>Updated 1 dependency</summary> [`bf60ab2`](bf60ab2) - `arkenv@0.12.3` </details> ## @arkenv/nuxt@0.0.6 ### Patch Changes - #### Improve npm keywords across published packages for discoverability _[`#1383`](#1383) [`bf60ab2`](bf60ab2) [@yamcodes](https://github.com/yamcodes)_ Clean up and extend the `keywords` field of every published package so npm search, aggregators, and LLM-powered package discovery surface ArkEnv for the terms users actually search for. - Remove the misleading `pnpm` keyword from `arkenv` and add `env`, `environment-variables`, `dotenv`, `config`, `standard-schema`, and the supported validators `zod` and `valibot`. - Deduplicate the repeated `arkenv` keyword in `@arkenv/vite-plugin`. - Give every env-related package a shared baseline (`env`, `environment-variables`, `dotenv`, `config`, `validation`, `typesafe`, `standard-schema`) alongside their integration-specific terms. - Add a keyword set to `@arkenv/fumadocs-ui`, which previously had none. - #### Type the `arkenv` key in `nuxt.config.ts` via `@nuxt/schema` augmentation _[`#1371`](#1371) [`7d541b4`](7d541b4) [@yamcodes](https://github.com/yamcodes)_ Augment `@nuxt/schema`'s `NuxtConfig` and `NuxtOptions` so the `arkenv` module options key is fully typed. Consumers now get autocomplete, type-checking, and JSDoc hovers for `arkenv` options directly in `nuxt.config.ts`, instead of falling back to a loose index signature. `ModuleOptions` is now an alias of the documented `ArkEnvConfigOptions`, so option hovers surface the existing JSDoc / `@default` tags from a single source of truth. ```ts export default defineNuxtConfig({ modules: ["@arkenv/nuxt/module"], arkenv: { schemaPath: "src/env.ts", // autocompleted & type-checked layout: "flat", validate: true, }, }); ``` <details><summary>Updated 1 dependency</summary> [`bf60ab2`](bf60ab2) - `arkenv@0.12.3` </details> ## @arkenv/vite-plugin@0.1.5 ### Patch Changes - #### Improve npm keywords across published packages for discoverability _[`#1383`](#1383) [`bf60ab2`](bf60ab2) [@yamcodes](https://github.com/yamcodes)_ Clean up and extend the `keywords` field of every published package so npm search, aggregators, and LLM-powered package discovery surface ArkEnv for the terms users actually search for. - Remove the misleading `pnpm` keyword from `arkenv` and add `env`, `environment-variables`, `dotenv`, `config`, `standard-schema`, and the supported validators `zod` and `valibot`. - Deduplicate the repeated `arkenv` keyword in `@arkenv/vite-plugin`. - Give every env-related package a shared baseline (`env`, `environment-variables`, `dotenv`, `config`, `validation`, `typesafe`, `standard-schema`) alongside their integration-specific terms. - Add a keyword set to `@arkenv/fumadocs-ui`, which previously had none. <details><summary>Updated 1 dependency</summary> [`bf60ab2`](bf60ab2) - `arkenv@0.12.3` </details> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

feat: drop -e short alias for --example (#1367)

1b42f74

Co-authored-by: Cursor <cursoragent@cursor.com>

yamcodes added enhancement New feature or improvement @arkenv/cli Issues or Pull Requests involving the ArkEnv CLI labels Jul 17, 2026

yamcodes linked an issue Jul 17, 2026 that may be closed by this pull request

CLI: drop -e short alias for --example (AI-hallucination trap) #1367

Closed

7 tasks

github-actions Bot added docs Adds or changes documentation, or acts as documentation in and of itself www Improvements or additions to arkenv.js.org tests This issue or PR is about adding, removing or changing tests labels Jul 17, 2026

pullfrog Bot approved these changes Jul 17, 2026

View reviewed changes

yamcodes merged commit b86b999 into dev Jul 17, 2026
26 checks passed

yamcodes deleted the 1367-cli-drop-e-short-alias-for-example-ai-hallucination-trap branch July 17, 2026 19:09

arkenv-bot Bot mentioned this pull request Jul 17, 2026

Version Packages #1374

Merged

yamcodes mentioned this pull request Jul 17, 2026

feat: (v1) Forward-port drop -e short alias for --example from #1370 #1378

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: drop `-e` short alias for `--example`#1370

feat: drop `-e` short alias for `--example`#1370
yamcodes merged 1 commit into
devfrom
1367-cli-drop-e-short-alias-for-example-ai-hallucination-trap

yamcodes commented Jul 17, 2026

Uh oh!

changeset-bot Bot commented Jul 17, 2026

Uh oh!

pkg-pr-new Bot commented Jul 17, 2026

Uh oh!

arkenv-bot Bot commented Jul 17, 2026

Uh oh!

pullfrog Bot left a comment

Uh oh!

arkenv-bot Bot commented Jul 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

yamcodes commented Jul 17, 2026

Why

Changes

Behavior

Follow-up

Uh oh!

changeset-bot Bot commented Jul 17, 2026

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Jul 17, 2026

Uh oh!

arkenv-bot Bot commented Jul 17, 2026

📦 Bundle Size Report

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

arkenv-bot Bot commented Jul 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant