bod-cli 0.10.8 → 0.10.10

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

@@ -134,17 +134,98 @@ 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
+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
 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 **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, 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 → `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. 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
+length is what makes the listing useful for **comparing** two values (spotting a
+truncated or whitespace-padded paste). It is not a byte count and not a grapheme count, so a decomposed-accent or flag-emoji string reports more than
+it visibly renders. Masking is **not** TTY-conditional: piping does not switch
+plaintext back on. For scripts use `--reveal`
+(byte-identical to the old `KEY=VALUE` output) or `bod env pull … --stdout`.
+`--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); 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.8",
+  "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
@@ -134,22 +135,105 @@ function diffEnv(existing: Record<string, string>, incoming: Record<string, stri
   return { added, changed, removed }
 }
 
+/** Characters that must never reach a table cell, in one place.
+ *  C0 + DEL + C1 (U+0080-U+009F: a bare U+009B is a CSI, which makes cli-table3
+ *  miscount the cell width and misalign every column after it), the Unicode line and
+ *  paragraph separators 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,
+ *  which is how a value lies about which key it belongs to. */
+const UNSAFE_CELL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200e\u200f\u202a-\u202e\u2066-\u2069]/g
+
+/** Shown instead of dots for a value that is the empty string: `••••••` with `len 0`
+ *  is indistinguishable from a masked secret at a glance, and "this var is set to
+ *  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 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 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
+ *  anyway — the length threshold above is the defence — and an exact length is what
+ *  makes the listing useful for spotting a truncated or whitespace-padded paste. It
+ *  counts codepoints of the resolved value: NOT a byte count and NOT a grapheme count
+ *  (a combining-accent/NFD or flag-emoji string reports more than it renders).
+ *  Compare it between two values; don't read it as "characters as a human counts". */
+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 / 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. */
+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. Per-app: resolved KEY=VALUE. --global/--group/--subs: variables in that scope (masked).' },
-  args: {
-    app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
-    env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
-    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>)' },
-  },
+  meta: { name: 'list', description: 'List env vars (values MASKED by default; --reveal prints them in full). --global/--group/--subs: variables in that scope.' },
+  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)
 
     const subs: SubsFlags = { subs: !!args.subs, subsApp: args['subs-app'] }
     assertScopeFlags(args.app, !!args.global, args.group, subs, args.env)
+    // The other scopes only ever receive server-side `masked` strings — there is no
+    // plaintext to reveal there. Say so instead of silently ignoring the flag.
+    if (args.reveal && (args.global || args.group || isSubsMode(subs))) {
+      console.error(chalk.red('--reveal only applies to the per-app scope; --global/--group/--subs return masked values from the server.'))
+      process.exit(1)
+    }
 
     if (isSubsMode(subs)) {
       const scopeApp = await buildSubsScopeApp(client, subs)
@@ -186,16 +270,127 @@ const listCmd = defineCommand({
       return
     }
 
-    // Per-app: show fully resolved values for the chosen environment.
+    // Per-app: the only scope that can resolve PLAINTEXT secrets. Mask unless asked.
     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
     }
-    for (const [k, v] of Object.entries(values)) console.log(`${k}=${v}`)
+
+    // Machine output: DELIBERATELY not TTY-conditional. Piping into a file or a log
+    // is exactly the case where leaking plaintext hurts most, so a pipe must not
+    // silently switch the output back to secrets — and a script must see what the
+    // human saw. Scripting keeps two explicit, unchanged paths: `--reveal` (emits the
+    // pre-masking KEY=VALUE format byte-for-byte) and `bod env pull --stdout`.
+    if (args.reveal) {
+      for (const [k, v] of Object.entries(values)) console.log(`${k}=${v}`)
+      return
+    }
+
+    printTable(
+      Object.entries(values).map(([key, v]) => {
+        const cell = maskValue(v)
+        return { key, value: cell === EMPTY_MARKER ? chalk.dim(cell) : cell, len: displayLength(v) }
+      }),
+      ['key', 'value', 'len'],
+    )
+    // Hint on stderr so stdout stays a clean, parseable table.
+    console.error(chalk.dim('  values masked — `bod env list … --reveal` to print them, or `bod env pull … --stdout`'))
+  },
+})
+
+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')
   },
 })
 
@@ -330,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)
@@ -353,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.
@@ -428,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

@@ -0,0 +1,251 @@
+// `bod env list <app>` is the ONLY scope that can resolve plaintext secrets. It must
+// mask them by default — including when piped — and reveal only on explicit request.
+// Verified at the REAL CLI surface (full citty parse) against a mock agent.
+import { test, expect, beforeAll, afterAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { maskValue, displayLength } from '../src/commands/env'
+
+const CLI = join(import.meta.dir, '..', 'src', 'cli.ts')
+const APP_ID = 'e1dba964-b944-4dd0-b971-fe72ee493bf6'
+const APP_NAME = 'blank'
+
+const REMOTE: Record<string, string> = {
+  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 -> 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
+  EMPTY_VAL: '',
+  // One fixture per control-char class, each 20 codepoints so a tail IS budgeted and
+  // the strip is actually exercised. Tail = the last 4 codepoints in every case.
+  C0_VAL: 'abcdefghijklmnop\r\n\tx',           // C0 + DEL family
+  DEL_VAL: 'abcdefghijklmnop\u007f\u007f\u007fx',
+  C1_VAL: 'abcdefghijklmnop\u009b\u0085\u0080x',     // U+009B = CSI (breaks table width), U+0085 = NEL
+  SEP_VAL: 'abcdefghijklmnop\u2028\u2029\u2028x',    // line / paragraph separators
+  BIDI_VAL: 'abcdefghijklmnop\u202e\u200f\u2066x', // RTL override + mark + isolate
+}
+
+// What the server returns for --global: it masks server-side, so `masked` is the
+// authoritative display string and the CLI must pass it through untouched.
+const GLOBAL_VARS = [
+  { key: 'SHARED_DB_URL', entries: [{ scope: {}, masked: 'post***rres', updatedAt: 0 }] },
+  { key: 'TEAM_TOKEN', entries: [{ scope: { group: 'infra' }, masked: 'ghp_***', updatedAt: 0 }] },
+]
+
+let server: ReturnType<typeof Bun.serve>
+let home: string
+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 }])
+      if (url.pathname === `/api/apps/${APP_ID}/env`) return Response.json({ values: REMOTE })
+      if (url.pathname === '/api/secrets/vars') return Response.json(GLOBAL_VARS)
+      return new Response('not found', { status: 404 })
+    },
+  })
+  home = mkdtempSync(join(tmpdir(), 'bod-list-home-'))
+  cwd = mkdtempSync(join(tmpdir(), 'bod-list-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(cwd, { recursive: true, force: true })
+})
+
+/** The `value` cell of one row of the masked table, for assertions that must not be
+ *  confused by the `len` column or another row. */
+function valueCell(stdout: string, key: string): string {
+  const row = stdout.split('\n').find(l => new RegExp(`\\|\\s*${key}\\s*\\|`).test(l))
+  if (!row) throw new Error(`no row for ${key} in:\n${stdout}`)
+  return row.split('|')[2]!.trim()
+}
+
+async function runCli(args: string[]) {
+  const proc = Bun.spawn(['bun', CLI, ...args], {
+    cwd,
+    env: { ...process.env, HOME: home, BOD_INSTANCE: '', FORCE_COLOR: '0' },
+    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 }
+}
+
+// NOTE: Bun.spawn gives the CLI a PIPE, not a TTY — so every test here is already the
+// piped case. Masking being non-TTY-conditional is what makes these assertions hold.
+test('masked by default (stdout is a pipe): keys visible, no plaintext secret anywhere', async () => {
+  const { code, stdout } = await runCli(['env', 'list', APP_NAME])
+  expect(code).toBe(0)
+  for (const k of Object.keys(REMOTE)) expect(stdout).toContain(k)
+  for (const v of Object.values(REMOTE)) if (v) expect(stdout).not.toContain(v)
+})
+
+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('ab' + DOTS + 'st')   // 20 cp -> floor(20/10) = 2
+  expect(valueCell(stdout, 'BOUND_19')).toBe(DOTS)
+  // 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*\|/)
+})
+
+test('a low-entropy value at the old boundary is no longer de-anonymised', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  const DOTS = '\u2022'.repeat(6)
+  // The regression this threshold exists for: `production` is 10 cp and used to render
+  // as ••••••on / len 10, which is the whole value.
+  expect(valueCell(stdout, 'LOW_ENTROPY')).toBe(DOTS)
+  expect(maskValue('production')).toBe(DOTS)
+  expect(maskValue('false')).toBe(DOTS)
+  expect(maskValue('true')).toBe(DOTS)
+})
+
+test('an empty value renders as (empty), not as a mask', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  expect(valueCell(stdout, 'EMPTY_VAL')).toBe('(empty)')
+  expect(valueCell(stdout, 'EMPTY_VAL')).not.toContain('\u2022')
+  expect(stdout).toMatch(/EMPTY_VAL\s*\|.*\|\s*0\s*\|/)
+  expect(maskValue('')).toBe('(empty)')
+})
+
+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('\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*\|/)
+})
+
+// Every class the strip must cover. A leaked one does one of two visible harms: it
+// breaks the row across lines (C0/NEL/LS/PS) or it reflows/miscounts the cell
+// (bidi override, C1 CSI) — so assert BOTH: one line, and not a single such char.
+const CONTROL_CASES: Array<[string, number, string, string[]]> = [
+  ['C0_VAL',   20, 'x', ['\r', '\n', '\t']],
+  ['DEL_VAL',  20, 'x', ['\u007f']],
+  ['C1_VAL',   20, 'x', ['\u009b', '\u0085', '\u0080']],
+  ['SEP_VAL',  20, 'x', ['\u2028', '\u2029']],
+  ['BIDI_VAL', 20, 'x', ['\u202e', '\u200f', '\u2066']],
+]
+
+test('control chars of every class are stripped and the row stays on one line', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  for (const [key, len, survivor, banned] of CONTROL_CASES) {
+    const cell = valueCell(stdout, key)
+    // '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))!
+    for (const c of banned) expect(row).not.toContain(c)
+    expect(row).toMatch(new RegExp(`${key}\\s*\\|[^\\n]*\\|\\s*${len}\\s*\\|`))
+  }
+  // Column alignment is intact: with no stray CSI miscounting a cell, every border
+  // rule is the same width. (This is what a leaked U+009B used to break.)
+  const rules = stdout.split('\n').filter(l => l.startsWith('+')).map(l => l.length)
+  expect(rules.length).toBeGreaterThan(1)
+  expect(new Set(rules).size).toBe(1)
+})
+
+test('--reveal prints full plaintext in the original KEY=VALUE format', async () => {
+  const { code, stdout } = await runCli(['env', 'list', APP_NAME, '--reveal'])
+  expect(code).toBe(0)
+  // Byte-identical to the pre-masking format: one KEY=VALUE line per var, raw values.
+  expect(stdout).toBe(Object.entries(REMOTE).map(([k, v]) => `${k}=${v}`).join('\n') + '\n')
+})
+
+test('the --reveal hint goes to stderr, keeping stdout parseable', async () => {
+  const { stdout, stderr } = await runCli(['env', 'list', APP_NAME])
+  expect(stderr).toContain('--reveal')
+  expect(stdout).not.toContain('--reveal')
+})
+
+test('--reveal is rejected on scopes that only ever hold masked server values', async () => {
+  const { code, stderr } = await runCli(['env', 'list', '--global', '--reveal'])
+  expect(code).toBe(1)
+  expect(stderr).toContain('--reveal only applies to the per-app scope')
+})
+
+test('--global passes the SERVER masked string through — maskValue is per-app only', async () => {
+  const { code, stdout } = await runCli(['env', 'list', '--global'])
+  expect(code).toBe(0)
+  for (const v of GLOBAL_VARS) {
+    expect(stdout).toContain(v.key)
+    expect(stdout).toContain(v.entries[0].masked)   // verbatim, not re-masked
+  }
+  expect(stdout).not.toContain('\u2022')
+  expect(stdout).not.toMatch(/\blen\b/)
+})
+
+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('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', () => {
+  expect(displayLength('\u{1F600}'.repeat(20))).toBe(20)   // not 40
+  expect(displayLength('abcdefghij\n')).toBe(11)
+})

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)
 })