bod-cli 0.10.9 → 0.10.10

package/.cursor/skills/using-bod-cli/SKILL.md

@@ -134,12 +134,14 @@ bod host ./dist --slug my-site     # reuse/update an existing slug
 bod host ./assets --app my-api     # persistent app assets
 ```
 
-### `bod env list|set|unset|pull <app>`
+### `bod env list|get|set|unset|pull <app>`
 Manage environment variables.
 
 ```bash
 bod env list my-api                   # values MASKED (key, masked value, length)
 bod env list my-api --reveal          # full plaintext, as KEY=VALUE lines
+bod env get my-api DATABASE_URL       # ONE value, plaintext, script-clean stdout
+bod env get DATABASE_URL              # app from bodify.yaml
 bod env set my-api DATABASE_URL=postgres://...
 bod env set my-api -f .env            # bulk set from .env file
 bod env unset my-api OLD_VAR
@@ -148,21 +150,27 @@ bod env pull my-api                   # write the resolved env to ./.env (0600)
 
 **`bod env list <app>` masks values by default.** It is the only scope that resolves
 plaintext secrets, and it used to print them straight to the terminal (and into any
-scrollback, log or pipe). The mask shows a short tail plus a length, enough to answer
-"is this the same key I have locally?" without exposing the value:
+scrollback, log or pipe). The mask shows a short **head and tail** plus a length, enough
+to answer "is this the same key I have locally?" without exposing the value:
 
-- **Under 20 codepoints → nothing is revealed.** A short value is usually low-entropy
-  (`production`, `true`, a PIN, a short enum) and a tail plus the length gives it away
-  outright — `••••••on` / len 10 *is* `production`. Real secrets are long, so this
+- **Under 20 codepoints → nothing is revealed, at either end.** A short value is usually
+  low-entropy (`production`, `true`, a PIN, a short enum) and a tail plus the length gives
+  it away outright — `••••••on` / len 10 *is* `production`. Real secrets are long, so this
   costs the useful case nothing.
-- **20 or more → `floor(len/5)` characters, capped at 4** — the familiar "…last four".
+- **20 or more → `min(4, floor(len/10))` at EACH end** — 20 cp → `ab••••••st`, 40 cp or
+  more → the 4+4 ceiling (`AKIA••••••WXYZ`). Total revealed stays ~20% of the value and
+  never exceeds 8 characters; head and tail can never overlap.
+- **The head is why this is not just "…last four".** Most consoles only ever show you the
+  *front* of a credential — AWS `AKIA…`, Stripe `sk_live_…`, a token prefix in a
+  dashboard — so a tail-only mask cannot be matched against any of them.
 - An **empty** value renders as a dim `(empty)`, not as dots: `••••••` with `len 0`
   would be indistinguishable from a masked secret.
 - Everything is counted in **Unicode codepoints**, so an emoji is never sliced in half.
   Characters that could corrupt the table are stripped from the tail: C0, DEL, C1
   (U+0080–U+009F — a bare U+009B is a CSI that misaligns every column), U+2028/U+2029,
   and the bidi controls (U+200E/U+200F, U+202A–U+202E, U+2066–U+2069) — U+202E alone
-  visually reverses the rest of the row.
+  visually reverses the rest of the row. The strip applies to **both** ends, so an end
+  made entirely of such characters simply reveals nothing (never more).
 
 The `len` column is that same codepoint count, and is deliberately **exact** — masking
 cannot defeat low entropy anyway (the 20-codepoint threshold is what does), and an exact
@@ -174,6 +182,50 @@ plaintext back on. For scripts use `--reveal`
 `--reveal` is rejected with `--global/--group/--subs`, which only ever receive
 server-side masked values.
 
+**`bod env get <app> KEY`** is the precise single-value read — the alternative to
+`bod env pull --stdout | grep`, which resolves and prints *every* secret just to read
+one. Plaintext is correct here: naming one key **is** the intent to see it, so there is
+no `--reveal`.
+
+```bash
+KEY=$(bod env get my-api DATABASE_URL)      # captures exactly the value
+bod env get my-api DATABASE_URL -e prod     # --env/-e works as on list/pull
+```
+
+- **stdout is the value and nothing else** — no key name, no colour, no decoration, one
+  trailing newline. `$(...)` strips it, and `read -r` needs it. Every diagnostic
+  (including the `Using app … from bodify.yaml` notice) goes to **stderr**.
+- **Exit codes are distinct**, because a script must tell "no such key" from "the agent
+  is down": **0** = the value was printed, **3** = the key is **not set** (a fact about
+  the app), **1** = the read **failed** (bad usage, `App not found: …`, HTTP 500,
+  connection refused, or a 200 whose body has no `values` — a server fault reported as
+  `Could not read env for this app`, never as "not set"). stdout stays empty on 1 and 3,
+  so a failed read can never land in the captured variable.
+
+  ```bash
+  V=$(bod env get my-api KEY); case $? in
+    0) ;;                       # got it
+    3) V=$DEFAULT ;;            # genuinely unset — falling back is correct
+    *) exit 1 ;;                # the read FAILED — do not fall back
+  esac
+  ```
+  Plain `V=$(bod env get …) || V=$DEFAULT` is the hazard this exists for: it would take
+  the default when the agent was merely unreachable.
+- A var set to the **empty string is set**: an empty line, exit 0 (not "missing").
+- One positional is read as the **KEY** (app from `bodify.yaml`); two are `<app> KEY`.
+  When a lone positional turns out to be unset, the message says so — `blank is not set
+  for this app (read as the KEY; …)` — because the word is often the *app* name the user
+  meant. **Three or more positionals are rejected**, never silently dropped.
+- **An unknown or mistyped flag is rejected (exit 1), never ignored.** citty drops a flag
+  the command never declared, so `--envv prod` used to return the *default* environment's
+  secret at exit 0 — and because the unknown flag swallows its own operand, the
+  extra-positional guard never saw it. A dangling `--env` with no value is rejected for
+  the same reason (it parses as `''` and silently falls back to the default). `list` and
+  `pull` get the same check.
+- `--global/--group/--subs` are **rejected**, like `list --reveal`: those scopes only ever
+  hold server-side masks, and a mask captured into a shell variable is a silent fake
+  secret. Use `bod env list` there.
+
 **`bod env pull` never clobbers an existing file.** A `.env` is hand-maintained and
 usually holds local-only credentials the server has never seen — replacing it can
 destroy the only copy. If the output file already exists, `pull` **refuses**, prints a

package/CLAUDE.md

@@ -33,7 +33,7 @@ src/
     ├── rollback.ts     # bod rollback [app]
     ├── apps.ts         # bod apps list|status
     ├── logs.ts         # bod logs <app> [-f]
-    ├── env.ts          # bod env list|set|unset|pull; scoped by <app>/--global/--group (+ --env); list MASKS values (--reveal for plaintext; never TTY-conditional); set supports -f .env; pull NEVER clobbers (--merge/--force/--stdout)
+    ├── env.ts          # bod env list|get|set|unset|pull; scoped by <app>/--global/--group (+ --env); list MASKS values (--reveal for plaintext; never TTY-conditional); get prints ONE value plaintext on script-clean stdout (per-app scope only; exit 3 = unset, 1 = read failed); set supports -f .env; pull NEVER clobbers (--merge/--force/--stdout)
     ├── open.ts         # bod open <app>
     ├── add.ts          # bod add <pkg>
     └── remove.ts       # bod remove <pkg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bod-cli",
-  "version": "0.10.9",
+  "version": "0.10.10",
   "type": "module",
   "bin": {
     "bod": "./src/cli.ts"

package/src/commands/env.ts

@@ -8,6 +8,7 @@ import { BodClient } from '../client'
 import { printTable } from '../utils/output'
 import { resolveAppId, resolveAppName } from '../utils/resolve'
 import { backupFile } from '../utils/safe-write'
+import { assertKnownFlags } from '../utils/args'
 
 // --- Subs PLATFORM PROVIDER scope (mirror bodify subs.secrets.ts) ---
 // Provider credentials (Stripe secret key, Apple shared secret, Play SA) are money
@@ -147,20 +148,41 @@ const UNSAFE_CELL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200e\u200f\u
  *  nothing" is a different, actionable fact. */
 export const EMPTY_MARKER = '(empty)'
 
+/** A 200 whose body carries no `values` object is a SERVER fault (a proxy error page, an
+ *  agent that changed shape, a half-written response), NOT an app with no variables.
+ *  `res.values ?? {}` silently turned that into "no vars" / "KEY is not set" — a false
+ *  factual claim about the app that a script then acts on (falls back to a default,
+ *  writes an empty dotenv file, reports the env as clean). Every reader of
+ *  /apps/:id/env goes through here so the fault is named as a fault, once. */
+function requireValues(res: ResolvedEnv | undefined): Record<string, string> {
+  if (!res || typeof res.values !== 'object' || res.values === null || Array.isArray(res.values)) {
+    console.error(chalk.red('Could not read env for this app: the server returned an unexpected response (no "values" object). This is a server fault - the variables were NOT read.'))
+    process.exit(1)
+  }
+  return res.values
+}
+
 /** Mask a resolved value for on-screen display.
  *
- *  The tail is what makes a mask USEFUL — it is how you answer "is the deployed key
- *  the same one I have locally?" without printing the secret. But a tail only stays
- *  safe when the value is long enough that a few characters cannot reconstruct it:
- *    len < 20  → 0 revealed. Anything shorter is likely low-entropy (`production`,
- *                `true`, a PIN, a short enum) and a tail plus the length column
- *                de-anonymises it outright — `••••••on` / len 10 IS `production`.
- *                Real secrets are long, so this costs the useful case nothing.
- *    len >= 20 → floor(len/5), capped at 4 — the familiar "…last four" affordance.
+ *  The revealed HEAD and TAIL are what make a mask USEFUL — they are how you answer
+ *  "is the deployed key the same one I have locally?" without printing the secret.
+ *  A head matters as much as a tail because most platforms only ever show you the
+ *  FRONT of a credential (AWS `AKIA…`, `sk_live_…`, a token prefix in a dashboard):
+ *  a tail-only mask cannot be matched against any of them.
+ *  Reveal only stays safe when the value is long enough that a few characters cannot
+ *  reconstruct it:
+ *    len < 20  → 0 revealed, at either end. Anything shorter is likely low-entropy
+ *                (`production`, `true`, a PIN, a short enum) and even a tail plus the
+ *                length column de-anonymises it outright — `••••••on` / len 10 IS
+ *                `production`. A head would give it away sooner still. Real secrets
+ *                are long, so this costs the useful case nothing.
+ *    len >= 20 → head = tail = min(4, floor(len/10)) codepoints — 20 → 2+2, 40+ → 4+4.
+ *                Total revealed stays ~20% of the value and never exceeds 8 characters.
+ *  Head and tail can never overlap: the budget is at most len/10 per side.
  *  Everything is measured in CODEPOINTS, not UTF-16 code units, so an odd budget
  *  cannot slice an astral character (emoji, some CJK) in half and emit a lone
  *  surrogate. The `len` column reports the same unit.
- *  UNSAFE_CELL_CHARS are dropped from the tail so a value cannot break, reverse or
+ *  UNSAFE_CELL_CHARS are dropped from BOTH ends so a value cannot break, reverse or
  *  misalign the table it is printed in.
  *
  *  NOTE on `len`: it is deliberately still exact. Masking cannot defeat low entropy
@@ -172,9 +194,11 @@ export const EMPTY_MARKER = '(empty)'
 export function maskValue(value: string): string {
   if (value === '') return EMPTY_MARKER
   const chars = [...value]
-  const reveal = chars.length < 20 ? 0 : Math.min(4, Math.floor(chars.length / 5))
-  const tail = reveal ? chars.slice(-reveal).join('').replace(UNSAFE_CELL_CHARS, '') : ''
-  return '••••••' + tail
+  const reveal = chars.length < 20 ? 0 : Math.min(4, Math.floor(chars.length / 10))
+  const safe = (part: string[]) => part.join('').replace(UNSAFE_CELL_CHARS, '')
+  const head = reveal ? safe(chars.slice(0, reveal)) : ''
+  const tail = reveal ? safe(chars.slice(-reveal)) : ''
+  return head + '••••••' + tail
 }
 
 /** Codepoint length — the unit the `len` column reports, matching maskValue's budget. */
@@ -182,18 +206,23 @@ export function displayLength(value: string): number {
   return [...value].length
 }
 
+const LIST_ARGS = {
+  app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
+  env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
+  reveal: { type: 'boolean', description: 'Print full plaintext values (per-app scope) as KEY=VALUE' },
+  global: { type: 'boolean', alias: 'g', description: 'List all variables across scopes (masked)' },
+  group: { type: 'string', description: 'List masked entries scoped to a group; excludes <app>/--global' },
+  subs: { type: 'boolean', description: 'List masked platform-GLOBAL subs provider secrets (__subs__~~global; money creds kept out of app envs)' },
+  'subs-app': { type: 'string', description: 'List masked per-app subs provider secrets for this app name/id (__subs__~<appId>)' },
+} as const
+
 const listCmd = defineCommand({
   meta: { name: 'list', description: 'List env vars (values MASKED by default; --reveal prints them in full). --global/--group/--subs: variables in that scope.' },
-  args: {
-    app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
-    env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
-    reveal: { type: 'boolean', description: 'Print full plaintext values (per-app scope) as KEY=VALUE' },
-    global: { type: 'boolean', alias: 'g', description: 'List all variables across scopes (masked)' },
-    group: { type: 'string', description: 'List masked entries scoped to a group; excludes <app>/--global' },
-    subs: { type: 'boolean', description: 'List masked platform-GLOBAL subs provider secrets (__subs__~~global; money creds kept out of app envs)' },
-    'subs-app': { type: 'string', description: 'List masked per-app subs provider secrets for this app name/id (__subs__~<appId>)' },
-  },
+  args: LIST_ARGS,
   async run({ args }) {
+    // Same hazard as on `get`, one step milder: a mistyped `--envv prod` would list a
+    // DIFFERENT environment's keys than the one asked for, at exit 0.
+    assertKnownFlags('env list', LIST_ARGS, args)
     const { url, apiKey } = getResolvedInstance(loadConfig())
     const client = new BodClient(url, apiKey)
 
@@ -245,7 +274,7 @@ const listCmd = defineCommand({
     const appId = await resolveAppId(client, resolveAppName(args.app))
     const qs = args.env ? `?environment=${encodeURIComponent(args.env)}` : ''
     const res = await client.get<ResolvedEnv>(`/apps/${appId}/env${qs}`)
-    const values = res.values ?? {}
+    const values = requireValues(res)
     if (Object.keys(values).length === 0) {
       console.log(chalk.dim('No environment variables set.'))
       return
@@ -273,6 +302,98 @@ const listCmd = defineCommand({
   },
 })
 
+const GET_ARGS = {
+  app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
+  key: { type: 'positional', description: 'Variable name', required: false },
+  env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
+  global: { type: 'boolean', alias: 'g', description: 'Not supported — that scope only holds masked values (see below)' },
+  group: { type: 'string', description: 'Not supported — that scope only holds masked values' },
+  subs: { type: 'boolean', description: 'Not supported — that scope only holds masked values' },
+  'subs-app': { type: 'string', description: 'Not supported — that scope only holds masked values' },
+} as const
+
+const getCmd = defineCommand({
+  meta: { name: 'get', description: "Print ONE variable's resolved plaintext value to stdout — script-friendly (KEY=$(bod env get <app> KEY)). Exit codes: 0 = printed, 3 = key is not set (a fact about the app), 1 = the read FAILED (bad usage, app not found, server/network fault)." },
+  args: GET_ARGS,
+  async run({ args }) {
+    // FIRST, before anything reads a flag: an UNDECLARED flag is silently dropped by
+    // citty, so `--envv prod` returned the DEFAULT environment's secret at exit 0 —
+    // straight into `K=$(bod env get …)`, with no error anywhere. The unknown flag also
+    // swallows its own operand, so the extra-positional guard below never sees it.
+    assertKnownFlags('env get', GET_ARGS, args)
+    const subs: SubsFlags = { subs: !!args.subs, subsApp: args['subs-app'] }
+
+    // Scope decision: REJECT --global/--group/--subs rather than return the mask.
+    // `get` exists to be captured (`K=$(bod env get …)`); returning `••••••abcd` there would
+    // silently put a fake secret into a variable — a mask is unmistakable to a human eye
+    // and invisible to a script. Same rule as `list --reveal`, which refuses these scopes
+    // for exactly the same reason. Because this rejects EVERY non-app scope up front,
+    // assertScopeFlags/resolvePositionals have nothing left to decide here: only <app>
+    // can be the primary axis, and --env is orthogonal to it.
+    if (args.global || args.group || isSubsMode(subs)) {
+      console.error(chalk.red('env get only supports the per-app scope; --global/--group/--subs return masked values from the server — use `bod env list` there.'))
+      process.exit(1)
+    }
+
+    // Positionals: `<app> KEY`, or a LONE `KEY` (app from bodify.yaml). Unlike `pull`,
+    // a lone positional needs no path/name heuristic — citty binds it to `app`, but a
+    // `get` with no KEY can do nothing at all, so the only useful reading of one
+    // positional is the KEY. Two positionals are always <app> KEY.
+    // Anything BEYOND two is rejected, never ignored: `bod env get app FOO EXTRA` used to
+    // print FOO and exit 0, so a typo'd flag or an unquoted value silently produced a
+    // confident answer to a question the user did not ask.
+    const positionals = (args._ ?? []).filter(a => typeof a === 'string') as string[]
+    if (positionals.length > 2) {
+      console.error(chalk.red(`env get takes at most <app> KEY — got ${positionals.length} positionals (unexpected: ${positionals.slice(2).join(', ')}). Quote a value containing spaces, or read one key per invocation.`))
+      process.exit(1)
+    }
+    const loneKey = !args.key
+    const app = args.key ? args.app : undefined
+    const key = args.key ?? args.app
+    if (!key) {
+      console.error(chalk.red('Variable name required: bod env get <app> KEY  (or `bod env get KEY` with a bodify.yaml)'))
+      process.exit(1)
+    }
+
+    const { url, apiKey } = getResolvedInstance(loadConfig())
+    const client = new BodClient(url, apiKey)
+    // resolveAppId exits 1 with "App not found: <name>" — a distinct message from the
+    // missing-key one below, so a script's stderr says WHICH of the two failed.
+    const appId = await resolveAppId(client, resolveAppName(app))
+    const qs = args.env ? `?environment=${encodeURIComponent(args.env)}` : ''
+    const res = await client.get<ResolvedEnv>(`/apps/${appId}/env${qs}`)
+    const values = requireValues(res)
+
+    // Object.hasOwn — not truthiness, and not `in`. A var set to the empty string IS
+    // set (so `values[key] !== undefined` is wrong), but `key in values` also walks the
+    // PROTOTYPE of the JSON.parse'd object: `bod env get app toString` printed the source
+    // of Function.prototype.toString, over SEVERAL lines, at exit 0 — so a script
+    // captured a fake multi-line "secret" instead of taking its unset branch, and
+    // `read -r` got a fragment of it. hasOwn keeps the empty-string semantics without
+    // the inherited keys.
+    if (!Object.hasOwn(values, key)) {
+      // Say HOW the argument was read. With one positional, `bod env get blank` in an app
+      // called `blank` prints "blank is not set" — which reads as "the app has no such
+      // var" when the user meant the app. Naming the interpretation makes the mistake
+      // visible instead of plausible.
+      const how = loneKey ? ' (read as the KEY; pass `bod env get <app> KEY` for an app)' : ''
+      console.error(chalk.red(`${key} is not set for this app${args.env ? ` in env "${args.env}"` : ''}${how}.`))
+      // Exit 3, NOT 1: "the key is not set" is a fact about the app, while 1 means the
+      // read did not happen (app not found, 500, connection refused, bad usage). They
+      // used to be indistinguishable, so `V=$(bod env get api KEY) || V=$DEFAULT` fell
+      // back to the default when the agent was merely DOWN — silently deploying the
+      // wrong value. A script that wants the fallback tests for 3.
+      process.exit(3)
+    }
+
+    // Trailing newline, deliberately: `$(...)` strips ALL trailing newlines, so it costs
+    // the capture case nothing, while a bare `bod env get` in a terminal and a
+    // `bod env get … | read -r V` both need the line terminated. No key name, no colour,
+    // no decoration — the value and nothing else.
+    process.stdout.write(values[key] + '\n')
+  },
+})
+
 const setCmd = defineCommand({
   meta: { name: 'set', description: 'Set a secret (KEY=VALUE or -f .env). Scoped to <app>, --global, --group, --subs/--subs-app, and/or --env.' },
   args: {
@@ -404,18 +525,24 @@ function looksLikePath(s: string): boolean {
   return s.includes('/') || s.startsWith('~') || s.startsWith('.')
 }
 
+const PULL_ARGS = {
+  app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
+  dest: { type: 'positional', description: 'Output file (default .env). A lone positional is only read as the destination when it is explicitly a path (./x, ~/x, a/b).', required: false },
+  env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
+  output: { type: 'string', alias: 'o', description: 'Output file (default .env)' },
+  stdout: { type: 'boolean', description: 'Print to stdout instead of writing any file' },
+  merge: { type: 'boolean', alias: 'm', description: 'Add only the keys missing from the file; never touch existing lines' },
+  force: { type: 'boolean', alias: 'F', description: 'Replace the whole file (a timestamped backup is written first)' },
+} as const
+
 const pullCmd = defineCommand({
   meta: { name: 'pull', description: 'Write an app\'s resolved env to a dotenv file (default .env, mode 0600). Refuses to clobber an existing file; use --merge or --force.' },
-  args: {
-    app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
-    dest: { type: 'positional', description: 'Output file (default .env). A lone positional is only read as the destination when it is explicitly a path (./x, ~/x, a/b).', required: false },
-    env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
-    output: { type: 'string', alias: 'o', description: 'Output file (default .env)' },
-    stdout: { type: 'boolean', description: 'Print to stdout instead of writing any file' },
-    merge: { type: 'boolean', alias: 'm', description: 'Add only the keys missing from the file; never touch existing lines' },
-    force: { type: 'boolean', alias: 'F', description: 'Replace the whole file (a timestamped backup is written first)' },
-  },
+  args: PULL_ARGS,
   async run({ args }) {
+    // A mistyped `--envv prod` here WRITES a different environment's secrets to disk, and
+    // a mistyped `--outt <path>` writes them to the default destination instead — both
+    // at exit 0, both harder to notice than a wrong value on stdout.
+    assertKnownFlags('env pull', PULL_ARGS, args)
     if (args.merge && args.force) {
       console.error(chalk.red('Pass only one of --merge, --force — they are mutually exclusive.'))
       process.exit(1)
@@ -427,7 +554,7 @@ const pullCmd = defineCommand({
     const appId = await resolveAppId(client, resolveAppName(app))
     const qs = args.env ? `?environment=${encodeURIComponent(args.env)}` : ''
     const res = await client.get<ResolvedEnv>(`/apps/${appId}/env${qs}`)
-    const values = res.values ?? {}
+    const values = requireValues(res)
     // Every branch below (fresh write / refuse / merge / force / backup) acts on THIS
     // resolved path. A destination that was silently dropped is how a real pull once
     // dumped 22 secrets into an unrelated repo's cwd.
@@ -502,5 +629,5 @@ const pullCmd = defineCommand({
 
 export default defineCommand({
   meta: { name: 'env', description: 'Manage environment variables (Bodify global secrets store)' },
-  subCommands: { list: listCmd, set: setCmd, unset: unsetCmd, rm: rmCmd, pull: pullCmd },
+  subCommands: { list: listCmd, get: getCmd, set: setCmd, unset: unsetCmd, rm: rmCmd, pull: pullCmd },
 })

package/src/utils/args.ts

@@ -0,0 +1,55 @@
+import chalk from 'chalk'
+
+/** Flags parsed from the WHOLE argv by cli.ts before citty dispatches, so they may
+ *  legally appear after the subcommand (`bod env get app KEY --instance staging`).
+ *  They are not declared on any subcommand, so they must be allowed explicitly. */
+const GLOBAL_FLAGS = ['instance', 'local', 'l']
+
+const camel = (name: string) => name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
+
+type ArgDef = { type?: string; alias?: string | string[]; default?: unknown }
+
+/** citty/mri SILENTLY ACCEPTS a flag the command never declared: `--envv prod` parses as
+ *  `envv: 'prod'` and the command reads its own (absent) `--env`, so it answers about the
+ *  DEFAULT environment at exit 0. On `env get` that lands another environment's secret in
+ *  a shell variable with no error at all — strictly worse than the extra-positional case,
+ *  which at least only ever returned a value the user did name. The positional guard
+ *  cannot see it, because the unknown flag swallows its own operand: `args._` stays at two.
+ *
+ *  A dangling string flag (`--env` with no operand) is the same failure wearing a
+ *  different hat: mri yields `''`, every `args.env ? …` is false, and the default
+ *  environment is used as if no flag had been passed. Rejected for the same reason.
+ *
+ *  Checked against the command's DECLARED args (names, their camelCase forms, and
+ *  aliases) so it cannot drift out of sync with them. Exits 1 — stdout untouched. */
+export function assertKnownFlags(cmd: string, declared: Record<string, ArgDef>, args: Record<string, unknown>): void {
+  const allowed = new Set<string>(['_', ...GLOBAL_FLAGS])
+  const stringFlags: string[] = []
+  for (const [name, def] of Object.entries(declared)) {
+    // Positionals are keys on `args` too (citty binds `<app>` to `args.app`), so they
+    // are allowed here even though they are not flags — they just never appear in the
+    // "Known:" list below, which is about what the user could have MISTYPED.
+    allowed.add(name)
+    allowed.add(camel(name))
+    if (def.type === 'positional') continue
+    for (const a of [def.alias ?? []].flat()) allowed.add(a)
+    if (def.type === 'string' && def.default !== '') stringFlags.push(name)
+  }
+
+  const unknown = Object.keys(args).filter(k => !allowed.has(k))
+  if (unknown.length) {
+    console.error(chalk.red(
+      `Unknown option${unknown.length > 1 ? 's' : ''} for \`bod ${cmd}\`: ${unknown.map(u => '--' + u).join(', ')}. ` +
+      `Known: ${[...new Set(Object.keys(declared).filter(n => declared[n]!.type !== 'positional'))].map(n => '--' + n).join(', ')}. ` +
+      `A mistyped flag is ignored by the parser, so this would otherwise have answered a different question at exit 0.`))
+    process.exit(1)
+  }
+
+  const dangling = stringFlags.filter(n => args[n] === '' || args[camel(n)] === '')
+  if (dangling.length) {
+    console.error(chalk.red(
+      `${dangling.map(n => '--' + n).join(', ')} needs a value (\`--${dangling[0]} <value>\`). ` +
+      `An empty one is not "unset" — it would silently fall back to the default.`))
+    process.exit(1)
+  }
+}

package/src/utils/resolve.ts

@@ -130,6 +130,9 @@ export function resolveAppName(arg: string | undefined): string {
     console.error(chalk.red('App name required. Pass <app> or run from a directory with bodify.yaml'))
     process.exit(1)
   }
-  console.log(chalk.dim(`Using app "${name}" from bodify.yaml`))
+  // stderr, not stdout: this is a diagnostic, never data. `bod env get` (and any other
+  // machine-readable stdout — `env list --reveal`, `env pull --stdout`) must stay clean
+  // enough that `X=$(bod env get app KEY)` captures the value and nothing else.
+  console.error(chalk.dim(`Using app "${name}" from bodify.yaml`))
   return name
 }

package/test/env-get.test.ts

@@ -0,0 +1,351 @@
+// `bod env get <app> KEY` is the precise, single-value read: plaintext, script-clean
+// stdout, non-zero + stderr when the key is unset. Verified at the REAL CLI surface
+// (full citty parse, real command substitution) against a mock agent.
+import { test, expect, beforeAll, afterAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+const CLI = join(import.meta.dir, '..', 'src', 'cli.ts')
+const APP_ID = 'e1dba964-b944-4dd0-b971-fe72ee493bf6'
+const APP_NAME = 'blank'
+// A second app whose /env returns a 200 with NO `values` — the shape a broken agent,
+// a proxy error page or a half-written response produces.
+const BROKEN_ID = '00000000-0000-4000-8000-000000000bad'
+const BROKEN_NAME = 'broken'
+
+const REMOTE: Record<string, string> = {
+  DATABASE_URL: 'postgres://u:p@db.internal:5432/app',
+  EMPTY_VAL: '',                       // set-to-nothing is SET, not missing
+  SPACED: 'a value  with   spaces',     // must survive capture byte-for-byte
+  MULTILINE: '-----BEGIN KEY-----\nabc\n-----END KEY-----',
+}
+const PROD: Record<string, string> = { DATABASE_URL: 'postgres://prod/app', PROD_ONLY: 'p1' }
+
+let server: ReturnType<typeof Bun.serve>
+let home: string
+let deadHome: string     // config pointing at a port nothing listens on
+let cwd: string
+
+beforeAll(() => {
+  server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname === '/api/apps') return Response.json([{ id: APP_ID, name: APP_NAME }, { id: BROKEN_ID, name: BROKEN_NAME }])
+      if (url.pathname === `/api/apps/${BROKEN_ID}/env`) return Response.json({ error: 'nope' })
+      if (url.pathname === `/api/apps/${APP_ID}/env`) {
+        return Response.json({ values: url.searchParams.get('environment') === 'prod' ? PROD : REMOTE })
+      }
+      if (url.pathname === '/api/secrets/vars') return Response.json([])
+      return new Response('not found', { status: 404 })
+    },
+  })
+  home = mkdtempSync(join(tmpdir(), 'bod-get-home-'))
+  deadHome = mkdtempSync(join(tmpdir(), 'bod-get-dead-'))
+  mkdirSync(join(deadHome, '.bod'), { recursive: true })
+  // Port 1 is reserved and never bound: connection refused, i.e. the agent is DOWN.
+  writeFileSync(join(deadHome, '.bod', 'config.json'), JSON.stringify({
+    defaultInstance: 'test',
+    instances: { test: { url: 'http://127.0.0.1:1', apiKey: 'test-key' } },
+  }))
+  cwd = mkdtempSync(join(tmpdir(), 'bod-get-cwd-'))
+  mkdirSync(join(home, '.bod'), { recursive: true })
+  writeFileSync(join(home, '.bod', 'config.json'), JSON.stringify({
+    defaultInstance: 'test',
+    instances: { test: { url: `http://localhost:${server.port}`, apiKey: 'test-key' } },
+  }))
+})
+
+afterAll(() => {
+  server?.stop(true)
+  rmSync(home, { recursive: true, force: true })
+  rmSync(deadHome, { recursive: true, force: true })
+  rmSync(cwd, { recursive: true, force: true })
+})
+
+const ENV = () => ({ ...process.env, HOME: home, BOD_INSTANCE: '', FORCE_COLOR: '0' })
+
+async function runCli(args: string[]) {
+  const proc = Bun.spawn(['bun', CLI, ...args], { cwd, env: ENV(), stdout: 'pipe', stderr: 'pipe' })
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited,
+  ])
+  return { stdout, stderr, code }
+}
+
+/** The actual consumer surface: a real shell doing `V=$(bod env get …); printf %s "$V"`. */
+async function captureInShell(script: string) {
+  const proc = Bun.spawn(['bash', '-c', script], {
+    cwd, env: { ...ENV(), CLI }, stdout: 'pipe', stderr: 'pipe',
+  })
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited,
+  ])
+  return { stdout, stderr, code }
+}
+
+test('prints exactly the value plus one newline — no key, no decoration', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL'])
+  expect(code).toBe(0)
+  expect(stdout).toBe(REMOTE.DATABASE_URL + '\n')
+  expect(stderr).toBe('')
+})
+
+test('command substitution yields the value byte-for-byte (newline stripped by $())', async () => {
+  const { code, stdout } = await captureInShell(`V=$(bun "$CLI" env get ${APP_NAME} DATABASE_URL); printf %s "$V"`)
+  expect(code).toBe(0)
+  expect(stdout).toBe(REMOTE.DATABASE_URL)
+})
+
+test('a value with spaces survives capture unchanged', async () => {
+  const { stdout } = await captureInShell(`V=$(bun "$CLI" env get ${APP_NAME} SPACED); printf %s "$V"`)
+  expect(stdout).toBe(REMOTE.SPACED)
+})
+
+test('the trailing newline lets `read` consume the first line', async () => {
+  const { stdout } = await captureInShell(`bun "$CLI" env get ${APP_NAME} DATABASE_URL | { read -r V; printf %s "$V"; }`)
+  expect(stdout).toBe(REMOTE.DATABASE_URL)
+})
+
+test('a multi-line value is emitted verbatim with exactly one added newline', async () => {
+  const { stdout } = await runCli(['env', 'get', APP_NAME, 'MULTILINE'])
+  expect(stdout).toBe(REMOTE.MULTILINE + '\n')
+})
+
+test('a var set to the empty string is SET: empty stdout line, exit 0', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, 'EMPTY_VAL'])
+  expect(code).toBe(0)
+  expect(stdout).toBe('\n')
+  expect(stderr).toBe('')
+})
+
+test('a missing key exits 3 with the message on stderr, stdout empty', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, 'NOPE'])
+  expect(code).toBe(3)          // 3 = "not set", NOT 1 = "the read failed"
+  expect(stdout).toBe('')
+  expect(stderr).toContain('NOPE is not set')
+})
+
+// The whole point of the split: `V=$(bod env get …) || V=$DEFAULT` must distinguish
+// "the app genuinely has no such key" from "the agent is DOWN". While both exited 1,
+// a dead agent silently produced the default — a wrong value shipped with no error.
+test('exit 3 vs 1: a real bash `||` fallback fires on unset and NOT on a dead agent', async () => {
+  const script = `
+    V=$(bun "$CLI" env get ${APP_NAME} "$1" 2>/dev/null); C=$?
+    if [ $C -eq 3 ]; then echo "FALLBACK"; else echo "code=$C"; fi`
+
+  // key is unset, agent healthy -> the script may safely fall back
+  const unset = await captureInShell(`set -- NOPE; ${script}`)
+  expect(unset.stdout.trim()).toBe('FALLBACK')
+
+  // agent DOWN (nothing listening) -> exit 1, so the fallback must NOT fire
+  const down = await captureInShell(`export HOME=${deadHome}; set -- DATABASE_URL; ${script}`)
+  expect(down.stdout.trim()).toBe('code=1')
+  expect(down.stdout).not.toContain('FALLBACK')
+
+  // and a malformed 200 is likewise 1, not 3
+  const broken = await captureInShell(`set -- DATABASE_URL; V=$(bun "$CLI" env get ${BROKEN_NAME} "$1" 2>/dev/null); C=$?; if [ $C -eq 3 ]; then echo FALLBACK; else echo "code=$C"; fi`)
+  expect(broken.stdout.trim()).toBe('code=1')
+})
+
+// A 200 with no `values` used to be read as an EMPTY env: `res.values ?? {}` turned a
+// server fault into the false factual claim "DASH is not set for this app", which a
+// script then acts on. It must fail as a read error instead.
+test('a malformed 200 is a read FAILURE, never "the key is not set"', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', BROKEN_NAME, 'DASH'])
+  expect(code).toBe(1)
+  expect(stdout).toBe('')
+  expect(stderr).toContain('Could not read env for this app')
+  expect(stderr).not.toContain('is not set')
+})
+
+test('the same malformed 200 fails list and pull rather than reporting an empty env', async () => {
+  const list = await runCli(['env', 'list', BROKEN_NAME])
+  expect(list.code).toBe(1)
+  expect(list.stderr).toContain('Could not read env for this app')
+  expect(list.stdout).not.toContain('No environment variables set')
+
+  const out = join(cwd, 'from-broken.vars')
+  const pull = await runCli(['env', 'pull', BROKEN_NAME, '-o', out])
+  expect(pull.code).toBe(1)
+  expect(pull.stderr).toContain('Could not read env for this app')
+  expect(existsSync(out)).toBe(false)      // and it wrote no empty file
+})
+
+// One positional is read as the KEY — which is invisible when the word is ALSO the app
+// name: `bod env get blank` in app `blank` used to say "blank is not set for this app",
+// reading as a fact about the app rather than a misparse of the argument.
+test('the unset message names how a lone positional was interpreted', async () => {
+  writeFileSync(join(cwd, 'bodify.yaml'), `name: ${APP_NAME}\n`)
+  try {
+    const { code, stderr } = await runCli(['env', 'get', APP_NAME])
+    expect(code).toBe(3)
+    expect(stderr).toContain(`${APP_NAME} is not set`)
+    expect(stderr).toContain('read as the KEY')
+    // Two positionals carry no ambiguity, so they get no such clause.
+    const two = await runCli(['env', 'get', APP_NAME, 'NOPE'])
+    expect(two.stderr).not.toContain('read as the KEY')
+  } finally {
+    rmSync(join(cwd, 'bodify.yaml'), { force: true })
+  }
+})
+
+// Extra positionals used to be dropped: `bod env get blank FOO EXTRA` printed FOO and
+// exited 0 — a confident answer to a question the user did not ask.
+test('extra positionals are rejected, not silently ignored', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL', 'EXTRA'])
+  expect(code).toBe(1)
+  expect(stdout).toBe('')                                  // the value did NOT leak out
+  expect(stdout).not.toContain(REMOTE.DATABASE_URL)
+  expect(stderr).toContain('at most <app> KEY')
+  expect(stderr).toContain('EXTRA')
+
+  // Four positionals are rejected the same way, and the message names every extra one.
+  const four = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL', 'A', 'B'])
+  expect(four.code).toBe(1)
+  expect(four.stdout).toBe('')
+  expect(four.stderr).toContain('at most <app> KEY')
+  expect(four.stderr).toContain('A, B')
+})
+
+// `key in values` walked the PROTOTYPE of the JSON.parse'd body: `bod env get blank
+// toString` printed the source of Function.prototype.toString — MULTI-LINE, at exit 0.
+// A script's `V=$(bod env get …) || V=$DEFAULT` captured that garbage instead of taking
+// its unset branch, and a `read -r V` got only the first fragment of it. Object.hasOwn
+// keeps the empty-string-is-set semantics without the inherited keys.
+test('prototype keys are NOT values: every one exits 3 with empty stdout', async () => {
+  for (const key of ['toString', 'constructor', '__proto__', 'hasOwnProperty', 'valueOf']) {
+    const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, key])
+    expect(`${key}:${code}`).toBe(`${key}:3`)
+    expect(stdout).toBe('')
+    expect(stderr).toContain(`${key} is not set`)
+  }
+  // And the real consumer surface: the `||` fallback fires, with nothing captured.
+  const shell = await captureInShell(
+    `V=$(bun "$CLI" env get ${APP_NAME} toString 2>/dev/null) || echo "FELLBACK"; printf '[%s]' "$V"`)
+  expect(shell.stdout).toContain('FELLBACK')
+  expect(shell.stdout).toContain('[]')
+  expect(shell.stdout).not.toContain('native code')
+})
+
+// citty/mri SILENTLY DROPS a flag the command never declared, and the extra-positional
+// guard cannot see it because the unknown flag swallows its own operand (`args._` stays
+// at two). So `--envv prod` returned the DEFAULT environment's secret at exit 0 — a
+// different environment's value landing in a shell variable with no error anywhere.
+test('an unknown flag is rejected, not ignored', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL', '--typo'])
+  expect(code).toBe(1)
+  expect(stdout).toBe('')
+  expect(stderr).toContain('Unknown option')
+  expect(stderr).toContain('--typo')
+})
+
+test('a mistyped --envv is rejected, NOT answered from the default environment', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL', '--envv', 'prod'])
+  expect(code).toBe(1)
+  expect(stdout).toBe('')
+  expect(stdout).not.toContain(REMOTE.DATABASE_URL)     // the WRONG env's value never printed
+  expect(stderr).toContain('--envv')
+})
+
+// `--env` with no operand parses as '', every `args.env ? …` is false, and the default
+// environment is silently used as if no flag had been passed.
+test('a dangling --env with no value is rejected', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL', '--env'])
+  expect(code).toBe(1)
+  expect(stdout).toBe('')
+  expect(stderr).toContain('--env needs a value')
+})
+
+// The declared flags, their aliases and the GLOBAL flags cli.ts parses out of the whole
+// argv must all still pass — the guard must reject typos, not legitimate usage.
+test('declared flags, aliases and global flags are still accepted', async () => {
+  for (const extra of [['--env', 'prod'], ['-e', 'prod'], ['--instance', 'test']]) {
+    const { code, stdout } = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL', ...extra])
+    expect(`${extra[0]}:${code}`).toBe(`${extra[0]}:0`)
+    expect(stdout.trim().startsWith('postgres://')).toBe(true)
+  }
+})
+
+// Pre-existing on list/pull, same citty behaviour, same wrong-environment hazard — and
+// on pull the wrong environment is WRITTEN to disk.
+test('list and pull reject an unknown flag too', async () => {
+  const list = await runCli(['env', 'list', APP_NAME, '--envv', 'prod'])
+  expect(list.code).toBe(1)
+  expect(list.stderr).toContain('--envv')
+
+  const out = join(cwd, 'typo.vars')
+  const pull = await runCli(['env', 'pull', APP_NAME, '--envv', 'prod', '-o', out])
+  expect(pull.code).toBe(1)
+  expect(pull.stderr).toContain('--envv')
+  expect(existsSync(out)).toBe(false)      // and no file was written from the wrong env
+})
+
+test('a missing key cannot poison the captured variable', async () => {
+  const { code, stdout } = await captureInShell(
+    `V=$(bun "$CLI" env get ${APP_NAME} NOPE 2>/dev/null) || echo "FAILED:[$V]"; printf %s "$V"`)
+  expect(code).toBe(0)
+  expect(stdout).toContain('FAILED:[]')
+})
+
+test('a missing APP is a distinct error from a missing key', async () => {
+  const { code, stderr } = await runCli(['env', 'get', 'no-such-app', 'DATABASE_URL'])
+  expect(code).toBe(1)
+  expect(stderr).toContain('App not found: no-such-app')
+  expect(stderr).not.toContain('is not set')
+})
+
+test('--env/-e selects the environment', async () => {
+  const a = await runCli(['env', 'get', APP_NAME, 'DATABASE_URL', '--env', 'prod'])
+  expect(a.code).toBe(0)
+  expect(a.stdout).toBe(PROD.DATABASE_URL + '\n')
+  const b = await runCli(['env', 'get', APP_NAME, 'PROD_ONLY', '-e', 'prod'])
+  expect(b.stdout).toBe('p1\n')
+  // A key that exists only in the default env is missing under --env, and says so.
+  const c = await runCli(['env', 'get', APP_NAME, 'SPACED', '-e', 'prod'])
+  expect(c.code).toBe(3)
+  expect(c.stderr).toContain('env "prod"')
+})
+
+test('no positional at all is a usage error, not an empty success', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get'])
+  expect(code).toBe(1)
+  expect(stdout).toBe('')
+  expect(stderr).toContain('Variable name required')
+})
+
+// A lone positional is the KEY (app from bodify.yaml) — `get` with no key is useless,
+// so that is its only useful reading. With no bodify.yaml it must NOT be read as an app.
+test('a lone positional with no bodify.yaml fails on the missing app, not silently', async () => {
+  const { code, stdout, stderr } = await runCli(['env', 'get', 'DATABASE_URL'])
+  expect(code).toBe(1)
+  expect(stdout).toBe('')
+  expect(stderr).toContain('App name required')
+})
+
+// Scope decision: the masked scopes are REJECTED, never returned as a mask — a mask
+// captured into a shell variable is a silent fake secret.
+test('--global/--group/--subs are rejected with a clear stderr message', async () => {
+  for (const flags of [['--global'], ['--group', 'infra'], ['--subs'], ['--subs-app', APP_NAME]]) {
+    const { code, stdout, stderr } = await runCli(['env', 'get', ...flags, 'DATABASE_URL'])
+    expect(code).toBe(1)
+    expect(stdout).toBe('')
+    expect(stderr).toContain('env get only supports the per-app scope')
+    expect(stderr).not.toContain('•')
+  }
+})
+
+test('the app falls back to bodify.yaml and its notice stays OFF stdout', async () => {
+  writeFileSync(join(cwd, 'bodify.yaml'), `name: ${APP_NAME}\n`)
+  try {
+    const { code, stdout, stderr } = await runCli(['env', 'get', 'DATABASE_URL'])
+    expect(code).toBe(0)
+    expect(stdout).toBe(REMOTE.DATABASE_URL + '\n')       // value ONLY
+    expect(stderr).toContain('from bodify.yaml')
+    const shell = await captureInShell(`V=$(bun "$CLI" env get DATABASE_URL 2>/dev/null); printf %s "$V"`)
+    expect(shell.stdout).toBe(REMOTE.DATABASE_URL)
+  } finally {
+    rmSync(join(cwd, 'bodify.yaml'), { force: true })
+  }
+})

package/test/env-list-mask.test.ts

@@ -12,9 +12,12 @@ const APP_ID = 'e1dba964-b944-4dd0-b971-fe72ee493bf6'
 const APP_NAME = 'blank'
 
 const REMOTE: Record<string, string> = {
-  STRIPE_KEY: 'sk_live_51NxAbCdEfGhIjKlMnOpQrStU',   // 33 cp -> 4 revealed
+  STRIPE_KEY: 'sk_live_51NxAbCdEfGhIjKlMnOpQrStU',   // 33 cp -> 3+3 revealed
+  AWS_KEY: 'AKIA' + 'X'.repeat(36),           // 40 cp -> 4+4: the HEAD is the half a
+                                              // console shows you (AKIA…), so it is the
+                                              // half a tail-only mask could never match
   BOUND_19: 'abcdefghijklmnopqrs',            // 19 cp -> 0 revealed (last length hidden)
-  BOUND_20: 'abcdefghijklmnopqrst',           // 20 cp -> 4 revealed (first length shown)
+  BOUND_20: 'abcdefghijklmnopqrst',           // 20 cp -> 2+2 revealed (first length shown)
   LOW_ENTROPY: 'production',                  // 10 cp -> 0: the tail used to give it away
   SHORT_PIN: '4821',
   EMOJI_VAL: '\u{1F600}'.repeat(20),            // astral: budget must not split a pair
@@ -96,14 +99,20 @@ test('masked by default (stdout is a pipe): keys visible, no plaintext secret an
   for (const v of Object.values(REMOTE)) if (v) expect(stdout).not.toContain(v)
 })
 
-test('reveal boundary: 19 codepoints show nothing, 20 show the last four', async () => {
+test('reveal boundary: 19 codepoints show nothing, 20 show two at EACH end', async () => {
   const { stdout } = await runCli(['env', 'list', APP_NAME])
   const DOTS = '\u2022'.repeat(6)
-  expect(valueCell(stdout, 'BOUND_20')).toBe(DOTS + 'qrst')
+  expect(valueCell(stdout, 'BOUND_20')).toBe('ab' + DOTS + 'st')   // 20 cp -> floor(20/10) = 2
   expect(valueCell(stdout, 'BOUND_19')).toBe(DOTS)
-  // and nothing of the 19-char value leaks by any suffix length
-  for (let i = 1; i <= 19; i++) expect(valueCell(stdout, 'BOUND_19')).not.toContain('abcdefghijklmnopqrs'.slice(-i))
-  expect(valueCell(stdout, 'STRIPE_KEY')).toBe(DOTS + 'rStU')      // 33 cp -> 4
+  // and nothing of the 19-char value leaks from EITHER end, at any length
+  for (let i = 1; i <= 19; i++) {
+    expect(valueCell(stdout, 'BOUND_19')).not.toContain('abcdefghijklmnopqrs'.slice(-i))
+    expect(valueCell(stdout, 'BOUND_19')).not.toContain('abcdefghijklmnopqrs'.slice(0, i))
+  }
+  expect(valueCell(stdout, 'STRIPE_KEY')).toBe('sk_' + DOTS + 'StU')   // 33 cp -> 3+3
+  // The head is the point of this shape: a dashboard showing only `AKIA…` can be
+  // matched against the listing, which a tail-only mask made impossible.
+  expect(valueCell(stdout, 'AWS_KEY')).toBe('AKIA' + DOTS + 'XXXX')    // 40 cp -> capped 4+4
   // Length is exact and still shown — it is what spots a truncated paste.
   expect(stdout).toMatch(/BOUND_19\s*\|.*\|\s*19\s*\|/)
   expect(stdout).toMatch(/BOUND_20\s*\|.*\|\s*20\s*\|/)
@@ -130,7 +139,7 @@ test('an empty value renders as (empty), not as a mask', async () => {
 
 test('astral values are sliced by codepoint — no lone surrogate, len counts codepoints', async () => {
   const { stdout } = await runCli(['env', 'list', APP_NAME])
-  expect(valueCell(stdout, 'EMOJI_VAL')).toBe('\u2022'.repeat(6) + '\u{1F600}'.repeat(4))
+  expect(valueCell(stdout, 'EMOJI_VAL')).toBe('\u{1F600}'.repeat(2) + '\u2022'.repeat(6) + '\u{1F600}'.repeat(2))
   expect(stdout).not.toContain('\uFFFD')
   for (const ch of stdout) expect(ch.codePointAt(0)! >= 0xd800 && ch.codePointAt(0)! <= 0xdfff).toBe(false)
   expect(stdout).toMatch(/EMOJI_VAL\s*\|.*\|\s*20\s*\|/)
@@ -151,7 +160,8 @@ test('control chars of every class are stripped and the row stays on one line',
   const { stdout } = await runCli(['env', 'list', APP_NAME])
   for (const [key, len, survivor, banned] of CONTROL_CASES) {
     const cell = valueCell(stdout, key)
-    expect(cell).toBe('\u2022'.repeat(6) + survivor)          // only the safe tail char survives
+    // 'ab' is the (safe) head; only the safe char of the tail survives the strip.
+    expect(cell).toBe('ab' + '\u2022'.repeat(6) + survivor)
     for (const c of banned) expect(cell).not.toContain(c)
     // ONE line: the key, the value and the len cell all sit on a single table row.
     const row = stdout.split('\n').find(l => l.includes(key))!
@@ -195,17 +205,44 @@ test('--global passes the SERVER masked string through — maskValue is per-app
   expect(stdout).not.toMatch(/\blen\b/)
 })
 
-test('maskValue budget: nothing below 20 codepoints, then floor(len/5) capped at 4', () => {
+test('maskValue budget: nothing below 20 codepoints, then head = tail = min(4, len/10)', () => {
   const DOTS = '\u2022'.repeat(6)
   expect(maskValue('4821')).toBe(DOTS)
   expect(maskValue('production')).toBe(DOTS)
-  expect(maskValue('a'.repeat(19))).toBe(DOTS)              // 19 -> still nothing
-  expect(maskValue('abcdefghijklmnopqrst')).toBe(DOTS + 'qrst')  // 20 -> the first tail
-  expect(maskValue('a'.repeat(100))).toBe(DOTS + 'aaaa')
-  expect(maskValue('\u{1F600}'.repeat(20))).toBe(DOTS + '\u{1F600}'.repeat(4))
-  expect(maskValue('\u{1F600}'.repeat(19))).toBe(DOTS)        // 19 codepoints (38 UTF-16 units)
-  // A tail that is ENTIRELY unsafe strips to nothing — reveals less, never more.
-  expect(maskValue('abcdefghijklmnop\u202e\u2028\u009b\r')).toBe(DOTS)
+  expect(maskValue('a'.repeat(19))).toBe(DOTS)                        // 19 -> still nothing
+  expect(maskValue('abcdefghijklmnopqrst')).toBe('ab' + DOTS + 'st')  // 20 -> the first 2+2
+  expect(maskValue('abcdefghijklmnopqrstuvwxyz1234')).toBe('abc' + DOTS + '234')   // 30 -> 3+3
+  expect(maskValue('b'.repeat(40))).toBe('bbbb' + DOTS + 'bbbb')      // 40 -> the 4+4 ceiling
+  expect(maskValue('a'.repeat(100))).toBe('aaaa' + DOTS + 'aaaa')     // still 4+4, never more
+  expect(maskValue('\u{1F600}'.repeat(20))).toBe('\u{1F600}'.repeat(2) + DOTS + '\u{1F600}'.repeat(2))
+  expect(maskValue('\u{1F600}'.repeat(19))).toBe(DOTS)                // 19 codepoints (38 UTF-16 units)
+  // An end that is ENTIRELY unsafe strips to nothing — reveals less, never more.
+  expect(maskValue('\u202e\u2028\u009b\rabcdefghijklmnop')).toBe(DOTS + 'op')
+  expect(maskValue('abcdefghijklmnop\u202e\u2028\u009b\r')).toBe('ab' + DOTS)
+})
+
+// The floor exists so head and tail can never meet: reveal is capped at len/10, so
+// 2*reveal <= len/5 < len for every value long enough to reveal anything at all. If
+// they ever DID overlap, the same characters would be shown twice and a 20-char value
+// would be printed whole.
+test('head and tail never overlap, at any length', () => {
+  const DOTS = '\u2022'.repeat(6)
+  for (let n = 20; n <= 60; n++) {
+    // Distinct-per-position value: an overlap would repeat a character across the dots.
+    const value = Array.from({ length: n }, (_, i) => String.fromCharCode(33 + (i % 90))).join('')
+    const masked = maskValue(value)
+    const [head, tail] = masked.split(DOTS)
+    expect(masked).toContain(DOTS)
+    expect(head!.length + tail!.length).toBeLessThanOrEqual(8)
+    expect(head!.length + tail!.length).toBeLessThanOrEqual(Math.floor(n / 5))
+    // Every revealed character comes from its own end of the value, and no index is
+    // claimed by both — head is a strict prefix, tail a strict suffix, and they are
+    // disjoint because their combined length is under n.
+    expect(value.startsWith(head!)).toBe(true)
+    expect(value.endsWith(tail!)).toBe(true)
+    expect(head!.length + tail!.length).toBeLessThan(n)
+    expect(new Set([...head! + tail!]).size).toBe(head!.length + tail!.length)
+  }
 })
 
 test('displayLength counts codepoints, matching the slicing unit', () => {

package/test/env-pull-guard.test.ts

@@ -225,9 +225,11 @@ test('the refusal guard applies to an explicit path destination', async () => {
 test('a LONE path positional is a destination, with the app from bodify.yaml', async () => {
   writeFileSync(join(cwd, 'bodify.yaml'), `name: ${APP_NAME}\n`)
   const dest = join(cwd, 'nested', 'out.vars')
-  const { code, stdout } = await runCli(['env', 'pull', dest])
+  const { code, stdout, stderr } = await runCli(['env', 'pull', dest])
   expect(code).toBe(0)
-  expect(stdout).toContain('from bodify.yaml')
+  // The fallback notice is a DIAGNOSTIC: stderr, so it can never pollute a captured stdout.
+  expect(stderr).toContain('from bodify.yaml')
+  expect(stdout).not.toContain('from bodify.yaml')
   expect(readFileSync(dest, 'utf8')).toBe(BODY)
   expect(existsSync(envPath())).toBe(false)
 })