envstash-cli 0.2.0 → 0.4.0

package/README.md

@@ -26,21 +26,28 @@ envs pull
 
 ## Commands
 
-| Command  | What it does                                      |
-| -------- | ------------------------------------------------- |
-| `login`  | Authorize this machine with a browser device code |
-| `logout` | Revoke this machine's token                       |
-| `whoami` | Show the signed-in account                        |
-| `init`   | Create a project and link this repo to it         |
-| `link`   | Link this repo to a project that already exists   |
-| `list`   | List every project in your account                |
-| `status` | Compare cloud files against local files           |
-| `diff`   | Show which keys differ, and how                   |
-| `pull`   | Write the cloud's version of each file to disk    |
-| `push`   | Send local files to the cloud                     |
+| Command   | What it does                                      |
+| --------- | ------------------------------------------------- |
+| `login`   | Authorize this machine with a browser device code |
+| `logout`  | Revoke this machine's token                       |
+| `whoami`  | Show the signed-in account                        |
+| `init`    | Create a project and link this repo to it         |
+| `link`    | Link this repo to a project that already exists   |
+| `list`    | List every project in your account                |
+| `status`  | Compare cloud files against local files           |
+| `diff`    | Show which keys differ, and how                   |
+| `pull`    | Write the cloud's version of each file to disk    |
+| `push`    | Send local files to the cloud                     |
+| `version` | Show the CLI version and its environment          |
 
 Run `envs help <command>` for details on any one of them.
 
+Every command accepts `-C <dir>` (or `--cwd <dir>`) to change to that directory
+first, like `git -C` — the repo, link file, and relative file arguments all
+resolve from there. Handy when the CLI itself must run from elsewhere, e.g.
+debugging with `pnpm run cli:dev status -C ~/projects/my-app` from the
+envstash checkout.
+
 ## `envs status`
 
 Checks every file in your cloud account against what is on disk.
@@ -125,9 +132,42 @@ files to track — and it is what lets a teammate clone the repo and run
 `envs pull` with no further setup.
 
 Without a link file the CLI guesses the project from your git remote's repo
-name and discovers `.env*` files in the repo root. Files ending in `.example`,
-`.sample`, `.template`, and `.dist` are ignored, since those are meant to be
-committed and hold placeholder values.
+name and discovers `.env*` files in the repo root, plus files in `.config/`
+(see below). Dotenv files ending in `.example`, `.sample`, `.template`, and
+`.dist` are ignored, since those are meant to be committed and hold placeholder
+values.
+
+### Files in `.config/`
+
+A service-account key or a cert is a secret that is not `KEY=value`, and it does
+not live in the repo root — so the dotenv scan cannot find it. When a `.config/`
+directory exists, discovery offers **everything in it**, subdirectories
+included — no extension allowlist, because a credential does not always look
+like one (an extensionless keyfile). A file is offered when **all** of these
+hold:
+
+- git ignores it,
+- it is not a document (`.md`, `.txt`, `.doc`, `.pdf`, and the like — notes,
+  not credentials),
+- it is under the 1 MB blob limit, and
+- its name is one the sync commands accept (`[A-Za-z0-9._-]` per segment).
+
+Being git-ignored is the signal for "secret": it is the repo's own statement
+that a file is not for sharing through git, which is exactly the population
+envstash exists to carry instead. A committed `.config/defaults.json` is left
+alone.
+
+Every git call the CLI makes clears `GIT_DIR`, `GIT_WORK_TREE` and the other
+location variables first. Git exports those to each hook it runs, and they
+override the working directory — so without clearing them, `envs status` in a
+pre-commit hook would answer about whichever repository invoked the hook rather
+than the one you are standing in.
+
+Outside a git repository, or if `git` is not installed, discovery adds nothing
+from `.config/` rather than guessing — over-discovery would upload a file nobody
+chose to share, while under-discovery just means listing it in `.envstash.json`
+by hand. The scan covers `.config/` and everything under it; files anywhere else
+are declared explicitly.
 
 Monorepos can track nested paths by listing them explicitly:
 
@@ -135,6 +175,27 @@ Monorepos can track nested paths by listing them explicitly:
 { "project": "my-monorepo", "files": ["apps/web/.env.local", "apps/api/.env"] }
 ```
 
+## Opaque files (service-account keys, certs)
+
+A tracked name whose basename is not `.env` or `.env.*` is stored **whole**, as
+one encrypted file, rather than parsed into keys:
+
+```json
+{ "project": "demo-app", "files": [".env", ".config/service-account.json"] }
+```
+
+Every command treats it as a single unit. `status` compares a digest of the raw
+bytes (never the bytes themselves), `push` sends the file when that digest
+changed, `pull` writes it back byte-for-byte with mode `0600`, and `diff`
+reports _that_ it changed but never prints the contents — `--show-values`
+included, because binary in a terminal helps no one. Opaque files are capped at
+1 MB: a stashed file should be a key or a cert, not an archive.
+
+Opaque files in `.config/` are auto-discovered (see above); one anywhere else
+enters only by being listed in `.envstash.json` or named as an argument:
+`envs push certs/server.pem`. For a name the cloud already knows, its recorded
+kind wins — a file cannot silently change identity between dotenv and opaque.
+
 ## Configuration
 
 | Variable              | Purpose                                                   |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envstash-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Git-style CLI for EnvStash — keep your .env files in sync with your cloud account.",
   "keywords": [
     "env",

package/src/api.mjs

@@ -18,8 +18,12 @@ export class ApiError extends CliError {
  * is not JSON (a proxy error page, a 502 from the edge) is reported as a
  * transport problem rather than crashing on a parse.
  */
-export async function request(host, path, { method = 'GET', token, body, signal } = {}) {
-  const headers = { accept: 'application/json' }
+export async function request(
+  host,
+  path,
+  { method = 'GET', token, body, signal, headers: extraHeaders } = {}
+) {
+  const headers = { accept: 'application/json', ...extraHeaders }
 
   if (token) {
     headers.authorization = `Bearer ${token}`
@@ -136,6 +140,10 @@ export const api = {
   getFile: (host, token, project, file) =>
     request(host, `/api/cli/projects/${encodeURIComponent(project)}/files/${encodePath(file)}`, {
       token,
+      // Declares that this CLI understands opaque file responses. The server
+      // refuses to send a blob to a client without it, because an older CLI
+      // would write it to disk as an empty dotenv file.
+      headers: { 'x-envstash-file-kinds': 'env,file' },
     }),
 
   putFile: (host, token, project, file, entries, prune) =>
@@ -144,6 +152,13 @@ export const api = {
       token,
       body: { entries, prune },
     }),
+
+  putBlob: (host, token, project, file, contentBase64) =>
+    request(host, `/api/cli/projects/${encodeURIComponent(project)}/files/${encodePath(file)}`, {
+      method: 'PUT',
+      token,
+      body: { kind: 'file', contentBase64 },
+    }),
 }
 
 /** Encode each path segment but keep the "/" separators that address a nested file. */

package/src/blob.mjs

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto'
+import { basename } from 'node:path'
+
+/**
+ * How a tracked name is classified when the cloud has no say yet: `.env` and
+ * `.env.*` basenames are dotenv files parsed into keys; everything else — a
+ * service-account JSON, a cert — is an opaque file stored whole. For names the
+ * cloud already knows, its recorded kind wins; this function only decides the
+ * kind of a file's first push.
+ */
+export function isEnvName(name) {
+  const base = basename(name)
+  return base === '.env' || base.startsWith('.env.')
+}
+
+/**
+ * Whole-file digest for opaque files: sha256 over raw bytes, truncated like the
+ * per-key digest. Must stay byte-identical to `fileDigest` in src/lib/crypto.ts.
+ */
+export function digestFileBytes(bytes) {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 12)
+}
+
+/** Mirror of MAX_BLOB_BYTES in src/lib/secrets/store.ts, checked before upload
+ *  so an oversized file fails locally with a clear message, not after a round trip. */
+export const MAX_BLOB_BYTES = 1024 * 1024
+
+/** "2.3 KB" for listings. Bytes below 1 KB print exact. */
+export function formatSize(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} B`
+  }
+
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`
+  }
+
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}

package/src/commands/diff.mjs

@@ -1,5 +1,6 @@
 import { api, ApiError } from '../api.mjs'
-import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import { formatSize } from '../blob.mjs'
+import { cloudKinds, loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
 import { entriesToMap } from '../env-file.mjs'
 import { compareProject, driftExitCode, FILE_STATE, KEY_STATE } from '../status.mjs'
 import { maskValue, out, style } from '../ui.mjs'
@@ -23,7 +24,7 @@ export async function diff(flags, args) {
     requested: args,
   })
 
-  const localFiles = loadLocalFiles(context.repoRoot, names)
+  const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const files = compareProject({
     cloudFiles: cloudFiles.filter(file => names.includes(file.name)),
     localFiles,
@@ -44,7 +45,7 @@ export async function diff(flags, args) {
 
   if (flags['show-values']) {
     for (const file of changed) {
-      if (file.state === FILE_STATE.UNTRACKED) {
+      if (file.state === FILE_STATE.UNTRACKED || file.kind === 'file') {
         continue
       }
 
@@ -63,6 +64,21 @@ export async function diff(flags, args) {
   for (const file of changed) {
     out(`  ${style.bold(file.name)} ${style.dim(`— ${describeFile(file)}`)}`)
 
+    if (file.kind === 'file') {
+      // A blob diffs as a whole: the digests already said the bytes differ, and
+      // dumping binary to a terminal helps no one — --show-values included.
+      if (file.state === FILE_STATE.DIFFERS) {
+        out(
+          `    ${style.yellow('~')} ${style.dim(
+            `file contents differ${file.size === undefined ? '' : ` (local ${formatSize(file.size)})`}` +
+              ' — binary, not shown'
+          )}`
+        )
+      }
+      out()
+      continue
+    }
+
     const local = entriesToMap(localFiles.get(file.name) ?? [])
     const cloud = cloudValues.get(file.name)
 

package/src/commands/misc.mjs

@@ -1,9 +1,80 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 import { api } from '../api.mjs'
-import { getStoredEmail } from '../config.mjs'
-import { discoverEnvFiles, findRepoRoot, readLink, resolveProject, writeLink } from '../project.mjs'
-import { requireHostToken, resolveHostFor } from '../session.mjs'
+import { configDir, getStoredEmail } from '../config.mjs'
+import {
+  discoverTrackedFiles,
+  findRepoRoot,
+  readLink,
+  resolveProject,
+  writeLink,
+} from '../project.mjs'
+import { requireHostToken, resolveHostFor, resolveHostSource } from '../session.mjs'
 import { out, pad, pluralize, style } from '../ui.mjs'
 
+/**
+ * `envs version` — the version, and the environment it would act in.
+ *
+ * `--version` and `-v` stay a bare semver for scripts to parse; this command is
+ * the human-facing one. The host line goes through the same resolution the sync
+ * commands use, so "which server would this talk to" is answered by the same
+ * code that would talk to it.
+ */
+export async function version(flags) {
+  const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+  let manifest = {}
+  try {
+    manifest = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
+  } catch {
+    // A broken install still deserves an answer; every field below has a fallback.
+  }
+
+  const { host, source } = resolveHostSource(flags)
+  const details = {
+    name: manifest.name ?? 'envstash-cli',
+    version: manifest.version ?? '0.0.0',
+    node: process.version,
+    platform: `${process.platform} ${process.arch}`,
+    installed: packageRoot,
+    host,
+    hostSource: source,
+    configDir: configDir(),
+  }
+
+  if (flags.json) {
+    out(JSON.stringify(details, null, 2))
+    return 0
+  }
+
+  const width = 12
+
+  out()
+  out(`  ${style.bold(details.name)} ${style.dim(`v${details.version}`)}`)
+  out()
+  out(`  ${pad('node', width)}${style.dim(details.node)}`)
+  out(`  ${pad('platform', width)}${style.dim(details.platform)}`)
+  out(`  ${pad('installed', width)}${style.dim(details.installed)}`)
+  out(`  ${pad('host', width)}${style.dim(`${details.host} (${sourceLabel(source)})`)}`)
+  out(`  ${pad('config', width)}${style.dim(details.configDir)}`)
+  out()
+
+  return 0
+}
+
+function sourceLabel(source) {
+  return (
+    {
+      flag: 'from --host or --port',
+      env: 'from the environment',
+      link: 'from .envstash.json',
+      default: 'default',
+    }[source] ?? source
+  )
+}
+
 /** `envs whoami` — which account this machine is signed in as. */
 export async function whoami(flags) {
   const { host, token } = requireHostToken(flags)
@@ -69,7 +140,7 @@ export async function init(flags, args) {
 
   await api.createProject(host, token, name)
 
-  const files = existing?.files?.length ? existing.files : discoverEnvFiles(repoRoot)
+  const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
   const path = writeLink(repoRoot, {
     project: name,
     files,
@@ -130,7 +201,7 @@ export async function link(flags, args) {
   // that points at nothing.
   await api.projectStatus(host, token, name)
 
-  const files = existing?.files?.length ? existing.files : discoverEnvFiles(repoRoot)
+  const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
   const path = writeLink(repoRoot, { project: name, files, host: existing?.host ?? null })
 
   out()

package/src/commands/pull.mjs

@@ -2,7 +2,8 @@ import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
 
 import { api, ApiError } from '../api.mjs'
-import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import { formatSize } from '../blob.mjs'
+import { cloudKinds, loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
 import { serializeEnv } from '../env-file.mjs'
 import { resolveInsideRepo } from '../repo-path.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
@@ -50,7 +51,7 @@ export async function pull(flags, args) {
     return 0
   }
 
-  const localFiles = loadLocalFiles(context.repoRoot, names)
+  const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const comparison = compareProject({
     cloudFiles: cloudFiles.filter(file => names.includes(file.name)),
     localFiles,
@@ -80,28 +81,34 @@ export async function pull(flags, args) {
     }
 
     const response = await api.getFile(context.host, context.token, context.project.name, file.name)
-    const body = serializeEnv(response.entries ?? [])
+
+    // A blob comes back whole; a dotenv file is regenerated from entries. The
+    // branch is on the response's own kind — the server is the authority.
+    const isBlob = response.kind === 'file'
+    const body = isBlob
+      ? Buffer.from(response.contentBase64 ?? '', 'base64')
+      : serializeEnv(response.entries ?? [])
+    const detail = isBlob
+      ? `(file, ${formatSize(body.length)})`
+      : `(${pluralize(response.entries?.length ?? 0, 'key')})`
+
     // Re-checked at the sink, not only where the name entered. This is the call
     // that creates directories and writes bytes, so it is the one that has to
     // be certain the path is inside the repo.
     const path = resolveInsideRepo(context.repoRoot, file.name)
 
     if (flags['dry-run']) {
-      out(
-        `  ${style.dim('would write')} ${file.name} ${style.dim(`(${pluralize(response.entries?.length ?? 0, 'key')})`)}`
-      )
+      out(`  ${style.dim('would write')} ${file.name} ${style.dim(detail)}`)
       continue
     }
 
     mkdirSync(dirname(path), { recursive: true })
-    // 0600: a pulled .env holds live credentials and has no business being
+    // 0600: a pulled secret holds live credentials and has no business being
     // readable by other accounts on a shared machine.
     writeFileSync(path, body, { mode: 0o600 })
     written += 1
 
-    out(
-      `  ${style.green('✓')} ${file.name} ${style.dim(`(${pluralize(response.entries?.length ?? 0, 'key')})`)}`
-    )
+    out(`  ${style.green('✓')} ${file.name} ${style.dim(detail)}`)
   }
 
   out()

package/src/commands/push.mjs

@@ -1,5 +1,6 @@
 import { api, ApiError } from '../api.mjs'
-import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import { formatSize, MAX_BLOB_BYTES } from '../blob.mjs'
+import { cloudKinds, loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
 import { CliError, out, pluralize, style } from '../ui.mjs'
 
@@ -22,11 +23,11 @@ export async function push(flags, args) {
     requested: args,
   })
 
-  const localFiles = loadLocalFiles(context.repoRoot, names)
+  const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const presentNames = names.filter(name => localFiles.get(name) !== null)
 
   if (presentNames.length === 0) {
-    throw new CliError('No local env files to push.', {
+    throw new CliError('No local files to push.', {
       hint: 'Create a .env file, or name one explicitly: `envs push .env.local`',
     })
   }
@@ -41,13 +42,17 @@ export async function push(flags, args) {
   let pushed = 0
 
   for (const file of comparison) {
-    const entries = localFiles.get(file.name) ?? []
-
     if (file.state === FILE_STATE.IN_SYNC && !flags.force) {
       out(`  ${style.dim('=')} ${file.name} ${style.dim('already up to date')}`)
       continue
     }
 
+    if (file.kind === 'file') {
+      pushed += await pushOneBlob(flags, context, file, localFiles.get(file.name))
+      continue
+    }
+
+    const entries = localFiles.get(file.name) ?? []
     const willDelete = flags.prune ? file.counts.cloud_only : 0
 
     if (flags['dry-run']) {
@@ -110,6 +115,47 @@ export async function push(flags, args) {
   return 0
 }
 
+/**
+ * Push one opaque file. Whole-file semantics: no prune, no per-key counts —
+ * the report is created / updated / unchanged, with the size, because "what
+ * went up" for a blob is the file itself.
+ */
+async function pushOneBlob(flags, context, file, local) {
+  if (local.bytes.length > MAX_BLOB_BYTES) {
+    throw new CliError(
+      `${file.name} is ${formatSize(local.bytes.length)} — files are capped at ${formatSize(MAX_BLOB_BYTES)}.`,
+      { hint: 'A stashed file should be a key or a cert, not an archive.' }
+    )
+  }
+
+  if (flags['dry-run']) {
+    out(
+      `  ${style.dim('would push')} ${file.name} ${style.dim(`(file, ${formatSize(local.bytes.length)})`)}`
+    )
+    return 0
+  }
+
+  const result = await api.putBlob(
+    context.host,
+    context.token,
+    context.project.name,
+    file.name,
+    local.bytes.toString('base64')
+  )
+
+  const note = result.created
+    ? style.green('new file')
+    : result.changed
+      ? style.yellow('updated')
+      : style.dim('no changes')
+
+  out(
+    `  ${style.green('✓')} ${file.name}  ${note}${style.dim(`, ${formatSize(local.bytes.length)}`)}`
+  )
+
+  return 1
+}
+
 async function fetchCloudFiles(context) {
   try {
     const response = await api.projectStatus(context.host, context.token, context.project.name)

package/src/commands/status.mjs

@@ -1,5 +1,6 @@
 import { api, ApiError } from '../api.mjs'
-import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import { formatSize } from '../blob.mjs'
+import { cloudKinds, loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
 import {
   compareProject,
   driftExitCode,
@@ -34,7 +35,7 @@ export async function status(flags, args) {
     requested: args,
   })
 
-  const localFiles = loadLocalFiles(context.repoRoot, names)
+  const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const files = compareProject({
     cloudFiles: cloudFiles.filter(file => names.includes(file.name)),
     localFiles,
@@ -80,7 +81,7 @@ function render(context, files) {
   out()
 
   if (files.length === 0) {
-    out(`  ${style.dim('No env files found locally or in the cloud.')}`)
+    out(`  ${style.dim('No files found locally or in the cloud.')}`)
     out()
     out(`  ${style.dim('Create some, then run')} envs push`)
     out()
@@ -119,6 +120,24 @@ function render(context, files) {
 }
 
 function fileSummary(file) {
+  if (file.kind === 'file') {
+    const size = file.size === undefined ? 'file' : `file, ${formatSize(file.size)}`
+
+    if (file.state === FILE_STATE.CLOUD_ONLY) {
+      return `${style.red('cloud only')} ${style.dim(`— ${size}, not on disk`)}`
+    }
+
+    if (file.state === FILE_STATE.UNTRACKED) {
+      return `${style.green('untracked')} ${style.dim(`— ${size}, not in the cloud`)}`
+    }
+
+    if (file.state === FILE_STATE.IN_SYNC) {
+      return style.dim(`up to date (${size})`)
+    }
+
+    return style.yellow('local file differs')
+  }
+
   if (file.state === FILE_STATE.CLOUD_ONLY) {
     return `${style.red('cloud only')} ${style.dim(`— ${pluralize(file.counts.cloud_only, 'key')}, not on disk`)}`
   }

package/src/context.mjs

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs'
 
+import { isEnvName } from './blob.mjs'
 import { parseEnvFile } from './env-file.mjs'
-import { discoverEnvFiles, findRepoRoot, readLink, resolveProject } from './project.mjs'
+import { discoverTrackedFiles, findRepoRoot, readLink, resolveProject } from './project.mjs'
 import { resolveInsideRepo } from './repo-path.mjs'
 import { requireHostToken } from './session.mjs'
 import { errOut, pluralize, style } from './ui.mjs'
@@ -25,7 +26,8 @@ export function resolveContext(flags) {
  * Explicit arguments win. Otherwise the link file's list is authoritative if
  * present — an explicit list is the only way to include a nested path like
  * `apps/web/.env.local`, which discovery does not scan for. With no link file,
- * fall back to the union of local `.env*` files and whatever the cloud holds.
+ * fall back to the union of what discovery finds — root `.env*` files plus git-ignored
+ * files in `.config/` — and whatever the cloud holds.
  */
 export function resolveFileNames({ repoRoot, link, cloudFiles, requested }) {
   if (requested?.length) {
@@ -36,7 +38,7 @@ export function resolveFileNames({ repoRoot, link, cloudFiles, requested }) {
     return check([...new Set(link.files)].sort())
   }
 
-  const names = new Set([...discoverEnvFiles(repoRoot), ...cloudFiles.map(file => file.name)])
+  const names = new Set([...discoverTrackedFiles(repoRoot), ...cloudFiles.map(file => file.name)])
 
   return check([...names].sort())
 }
@@ -61,8 +63,14 @@ function check(names) {
 /**
  * Read the named files off disk. A missing file maps to null rather than being
  * skipped, so the comparison can distinguish "not on disk" from "empty".
+ *
+ * `kinds` carries the cloud's recorded kind per name; a name the cloud has not
+ * seen is classified by `isEnvName`. Dotenv files parse into entry arrays; an
+ * opaque file reads as raw bytes and maps to `{ kind: 'file', bytes }` — no
+ * parsing, no warnings about lines, because a JSON key has no KEY=value lines
+ * and that is not a defect.
  */
-export function loadLocalFiles(repoRoot, names) {
+export function loadLocalFiles(repoRoot, names, kinds = new Map()) {
   const files = new Map()
 
   for (const name of names) {
@@ -75,6 +83,13 @@ export function loadLocalFiles(repoRoot, names) {
       continue
     }
 
+    const kind = kinds.get(name) ?? (isEnvName(name) ? 'env' : 'file')
+
+    if (kind === 'file') {
+      files.set(name, { kind: 'file', bytes: readFileSync(path) })
+      continue
+    }
+
     const { entries, skipped } = parseEnvFile(readFileSync(path, 'utf8'))
 
     files.set(name, entries)
@@ -87,6 +102,11 @@ export function loadLocalFiles(repoRoot, names) {
   return files
 }
 
+/** The cloud's recorded kind per file name, for `loadLocalFiles`. */
+export function cloudKinds(cloudFiles) {
+  return new Map(cloudFiles.map(file => [file.name, file.kind ?? 'env']))
+}
+
 /**
  * Say out loud that part of a file was not understood.
  *

package/src/index.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 
 import { diff } from './commands/diff.mjs'
 import { login, logout } from './commands/login.mjs'
-import { init, link, list, whoami } from './commands/misc.mjs'
+import { init, link, list, version as versionCommand, whoami } from './commands/misc.mjs'
 import { pull } from './commands/pull.mjs'
 import { push } from './commands/push.mjs'
 import { status } from './commands/status.mjs'
@@ -16,10 +16,25 @@ import { CliError, errOut, out, style } from './ui.mjs'
  * Flags that take a value. Everything else is a boolean, which is what lets
  * `--force` and `--project my-app` be parsed without a schema per command.
  */
-const VALUE_FLAGS = new Set(['host', 'port', 'project', 'label'])
+const VALUE_FLAGS = new Set(['host', 'port', 'project', 'label', 'cwd'])
+
+/** Git-style `-C <dir>`: the one short flag that takes a value. */
+const SHORT_VALUE_ALIASES = { C: 'cwd' }
 
 /** The implementation of each command, by name. */
-const HANDLERS = { login, logout, whoami, init, link, list, status, diff, pull, push }
+const HANDLERS = {
+  login,
+  logout,
+  whoami,
+  init,
+  link,
+  list,
+  status,
+  diff,
+  pull,
+  push,
+  version: versionCommand,
+}
 
 /**
  * Summaries and aliases come from the manifest rather than being repeated here,
@@ -85,6 +100,14 @@ export function parseArgs(argv) {
     }
 
     if (token.startsWith('-') && token.length > 1) {
+      const alias = SHORT_VALUE_ALIASES[token.slice(1)]
+
+      if (alias) {
+        flags[alias] = argv[index + 1]
+        index += 2
+        continue
+      }
+
       flags[token.slice(1)] = true
       index += 1
       continue
@@ -116,7 +139,9 @@ export async function run(argv) {
   const { flags, args } = parseArgs(argv)
   const [name, ...rest] = args
 
-  if (flags.version || flags.v || name === 'version') {
+  // Bare semver only, for scripts to parse. `envs version` — the command — is
+  // the detailed, human-facing answer.
+  if (flags.version || flags.v) {
     out(version())
     return finish(0)
   }
@@ -136,6 +161,7 @@ export async function run(argv) {
   }
 
   try {
+    changeDirectory(flags)
     const code = await command.run(flags, rest)
     return finish(code ?? 0)
   } catch (error) {
@@ -166,6 +192,37 @@ export async function run(argv) {
   }
 }
 
+/**
+ * `-C <dir>` / `--cwd <dir>`: run as if launched from that directory.
+ *
+ * Every command resolves its repo from the working directory, which is wrong by
+ * definition when the CLI is run from a different repo — the motivating case is
+ * `pnpm run cli:dev`, which must execute from the envstash checkout while
+ * answering about some other project. Changing directory before dispatch covers
+ * every command at once, exactly like `git -C`.
+ */
+function changeDirectory(flags) {
+  if (!('cwd' in flags)) {
+    return
+  }
+
+  const target = flags.cwd
+
+  if (typeof target !== 'string' || target === '') {
+    throw new CliError('The -C / --cwd option needs a directory.', {
+      hint: 'Example: envs status -C ~/projects/my-app',
+    })
+  }
+
+  try {
+    process.chdir(target)
+  } catch {
+    throw new CliError(`Cannot change directory to ${JSON.stringify(target)}.`, {
+      hint: 'Check that it exists and is a directory.',
+    })
+  }
+}
+
 /**
  * Set the exit code rather than calling process.exit, so buffered stdout is
  * flushed before the process ends. `process.exit` truncates output when stdout
@@ -195,10 +252,13 @@ function printHelp(topic) {
 
   out()
   out(`  ${style.bold('Common options')}`)
+  out(`    -C, --cwd <dir>    ${style.dim('Change to this directory before doing anything')}`)
   out(`    --project <name>   ${style.dim('Target a project other than the linked one')}`)
   out(`    --host <url>       ${style.dim('Target another EnvStash server')}`)
   out(`    --port <n>         ${style.dim('Target a dev server on localhost at this port')}`)
-  out(`    --json             ${style.dim('Machine-readable output (status, list, whoami)')}`)
+  out(
+    `    --json             ${style.dim('Machine-readable output (status, list, whoami, version)')}`
+  )
   out(`    --exit-zero        ${style.dim('Always exit 0, even when out of sync (status, diff)')}`)
   out(`    --dry-run          ${style.dim('Show what would happen (pull, push)')}`)
   out(`    --dev              ${style.dim('Log in to a local dev server if one is running')}`)
@@ -294,6 +354,13 @@ const COMMAND_HELP = {
   link: ['Link this repo to a project that already exists.', '', '  envs link my-app'],
   list: ['List every project in your account.', '', '  envs list', '  envs list --json'],
   whoami: ['Show which account this machine is signed in as.', '', '  envs whoami'],
+  version: [
+    'Show the version, runtime, install path, and which server commands would',
+    'talk to. --version and -v print the bare version for scripts.',
+    '',
+    '  envs version',
+    '  envs version --json',
+  ],
 }
 
 function printCommandHelp(name) {

package/src/manifest.mjs

@@ -27,6 +27,7 @@ export const CLI_COMMANDS = [
   { name: 'diff', summary: 'Show which keys differ, and how' },
   { name: 'pull', summary: 'Write the cloud’s version of each file to disk' },
   { name: 'push', summary: 'Send local files to the cloud' },
+  { name: 'version', summary: 'Show the CLI version and its environment' },
 ]
 
 /**

package/src/project.mjs

@@ -1,13 +1,55 @@
 import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
-import { basename, dirname, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve, sep } from 'node:path'
 
-import { keepSafeRepoPaths } from './repo-path.mjs'
+import { MAX_BLOB_BYTES } from './blob.mjs'
+import { isSafeRepoPath, keepSafeRepoPaths } from './repo-path.mjs'
 import { CliError } from './ui.mjs'
 
 /** The per-repo link file. Safe to commit — it names files, never values. */
 export const LINK_FILE = '.envstash.json'
 
+/**
+ * Environment variables by which git decides *which repository it is operating on*,
+ * overriding both the working directory and `-C`.
+ *
+ * Git exports these to every hook it runs. The README recommends `envs status` in a
+ * pre-commit hook, so this is not a hypothetical: with `GIT_DIR` inherited, a `git`
+ * call meant to ask about `repoRoot` silently answers about — or writes to — whatever
+ * repository invoked the hook, no matter what `cwd` says.
+ */
+const GIT_LOCATION_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_COMMON_DIR',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_PREFIX',
+]
+
+/**
+ * Run git against `cwd` and mean it.
+ *
+ * Every git call here is a question about one specific directory, so the inherited
+ * location variables are cleared and `cwd` is left as the only thing that decides.
+ */
+function runGit(args, { cwd, input } = {}) {
+  const env = { ...process.env }
+  for (const name of GIT_LOCATION_VARS) {
+    delete env[name]
+  }
+
+  return execFileSync('git', args, {
+    cwd,
+    env,
+    ...(input === undefined ? {} : { input }),
+    encoding: 'utf8',
+    stdio: input === undefined ? ['ignore', 'pipe', 'ignore'] : ['pipe', 'pipe', 'ignore'],
+  })
+}
+
 /**
  * Files that look like `.env` but are meant to be committed and contain no real
  * secrets. Auto-including them would push placeholder values over the top of a
@@ -90,11 +132,7 @@ export function writeLink(repoRoot, link) {
  */
 export function guessProjectName(repoRoot) {
   try {
-    const remote = execFileSync('git', ['config', '--get', 'remote.origin.url'], {
-      cwd: repoRoot,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim()
+    const remote = runGit(['config', '--get', 'remote.origin.url'], { cwd: repoRoot }).trim()
 
     if (remote) {
       const name = basename(remote.replace(/\.git$/, ''))
@@ -140,6 +178,113 @@ export function discoverEnvFiles(repoRoot) {
     .sort()
 }
 
+/**
+ * Where credential *files* live, by convention: a service-account JSON, a cert, a
+ * private key — the things that are secrets but are not `KEY=value`.
+ */
+export const SECRET_FILE_DIR = '.config'
+
+/**
+ * Which of `names` git ignores, as a Set.
+ *
+ * Being ignored is the signal this uses for "secret". It is the repo's own
+ * declaration that a file is not for sharing through git, which is exactly the
+ * population envstash exists to carry instead — and it means a committed
+ * `.config/defaults.json` is left alone rather than uploaded.
+ *
+ * Any failure yields the empty set, so discovery adds nothing. That is the
+ * conservative direction here: over-discovery uploads a file the developer never
+ * chose to share, while under-discovery only means they list it by hand, which is
+ * what they do today.
+ */
+function gitIgnoredNames(repoRoot, names) {
+  if (names.length === 0) {
+    return new Set()
+  }
+
+  try {
+    const output = runGit(['check-ignore', '--stdin'], { cwd: repoRoot, input: names.join('\n') })
+    return new Set(output.split('\n').filter(Boolean))
+  } catch (error) {
+    // `git check-ignore` exits 1 when nothing matched — a real answer, not a
+    // failure, and stdout still holds whatever did match.
+    if (error?.status === 1 && typeof error.stdout === 'string') {
+      return new Set(error.stdout.split('\n').filter(Boolean))
+    }
+    return new Set()
+  }
+}
+
+/**
+ * Documentation, not credentials. A `.config/` directory often carries a README
+ * or notes alongside the keys; pushing those adds noise without protecting a
+ * secret.
+ */
+const DOCUMENT_SUFFIXES = [
+  '.md',
+  '.markdown',
+  '.rst',
+  '.txt',
+  '.rtf',
+  '.doc',
+  '.docx',
+  '.odt',
+  '.pdf',
+]
+
+/**
+ * Discover files in `.config/` — all of them, except documents.
+ *
+ * The dotenv scan above cannot find these: they are not named `.env*` and they do
+ * not live in the repo root. Before this existed, a project with a service-account
+ * key had to hand-write it into `.envstash.json` and remember to do so again on the
+ * next one.
+ *
+ * No extension allowlist: a credential does not always look like one (an
+ * extensionless keyfile), so when the directory exists, everything in it is
+ * offered — recursively, since credential tooling nests (`.config/gcloud/…`) —
+ * minus document files, which are never credentials. Git-ignore remains the gate:
+ * a file is offered only when it is git-ignored, small enough to push, and has a
+ * name the sync commands will accept.
+ */
+export function discoverSecretFiles(repoRoot) {
+  const directory = join(repoRoot, SECRET_FILE_DIR)
+  let entries
+
+  try {
+    entries = readdirSync(directory, { recursive: true })
+  } catch {
+    return []
+  }
+
+  const candidates = entries
+    // Nested entries come back joined with the platform separator; names are POSIX.
+    .map(entry => `${SECRET_FILE_DIR}/${entry.split(sep).join('/')}`)
+    .filter(name => !DOCUMENT_SUFFIXES.some(suffix => name.toLowerCase().endsWith(suffix)))
+    // The grammar the server and `resolveInsideRepo` both enforce. Discovering a
+    // name they would refuse produces a link file that cannot be pushed.
+    .filter(name => isSafeRepoPath(name))
+    .filter(name => {
+      try {
+        const stats = statSync(join(repoRoot, name))
+        // Skipping oversized files here means `envs init` never lists something
+        // whose first push would fail.
+        return stats.isFile() && stats.size <= MAX_BLOB_BYTES
+      } catch {
+        return false
+      }
+    })
+
+  const ignored = gitIgnoredNames(repoRoot, candidates)
+
+  return candidates.filter(name => ignored.has(name)).sort()
+}
+
+/** Everything auto-discovery offers to track: root dotenv files, then `.config/` files. */
+export function discoverTrackedFiles(repoRoot) {
+  return [...discoverEnvFiles(repoRoot), ...discoverSecretFiles(repoRoot)]
+}
+
 /**
  * Resolve which project this invocation targets: `--project` wins, then the link
  * file, then the repo-name guess.

package/src/status.mjs

@@ -1,3 +1,4 @@
+import { digestFileBytes } from './blob.mjs'
 import { digestValue } from './env-file.mjs'
 
 /**
@@ -64,7 +65,48 @@ export function compareFile(name, localEntries, cloudKeys) {
 
   const counts = countStates(keys)
 
-  return { name, state: fileState(localEntries, cloudKeys, counts), keys, counts }
+  return { name, kind: 'env', state: fileState(localEntries, cloudKeys, counts), keys, counts }
+}
+
+/**
+ * Compare one opaque file. The whole file is the unit, so the counts record it
+ * as a single entry — which keeps `summarize` and the drift exit code honest
+ * without a special case: one drifted blob counts exactly one drifted thing.
+ *
+ * `local` is `{ kind: 'file', bytes }` or null; `cloud` is the status entry
+ * (with `digest` and `size`) or null.
+ */
+export function compareBlobFile(name, local, cloud) {
+  if (local === null && !cloud) {
+    return null
+  }
+
+  const localDigest = local ? digestFileBytes(local.bytes) : null
+  const counts = { same: 0, modified: 0, local_only: 0, cloud_only: 0 }
+  let state
+
+  if (!cloud) {
+    state = FILE_STATE.UNTRACKED
+    counts.local_only = 1
+  } else if (local === null) {
+    state = FILE_STATE.CLOUD_ONLY
+    counts.cloud_only = 1
+  } else if (localDigest === cloud.digest) {
+    state = FILE_STATE.IN_SYNC
+    counts.same = 1
+  } else {
+    state = FILE_STATE.DIFFERS
+    counts.modified = 1
+  }
+
+  return {
+    name,
+    kind: 'file',
+    state,
+    keys: [],
+    counts,
+    size: local?.bytes.length ?? cloud?.size,
+  }
 }
 
 function countStates(keys) {
@@ -105,7 +147,17 @@ export function compareProject({ cloudFiles, localFiles }) {
 
   for (const name of [...names].sort()) {
     const cloud = cloudFiles.find(file => file.name === name)
-    const comparison = compareFile(name, localFiles.get(name) ?? null, cloud?.keys ?? null)
+    const local = localFiles.get(name) ?? null
+
+    // The cloud's recorded kind wins; a file it has never seen is classified by
+    // how `loadLocalFiles` read it. The two agree by construction — local blobs
+    // are only produced for names the cloud calls 'file' or names not in the
+    // cloud that fail the dotenv naming test.
+    const isBlob = cloud?.kind === 'file' || (local !== null && local.kind === 'file')
+
+    const comparison = isBlob
+      ? compareBlobFile(name, local, cloud ?? null)
+      : compareFile(name, local, cloud?.keys ?? null)
 
     if (comparison) {
       files.push(comparison)