envstash-cli 0.1.1 → 0.3.0

package/README.md

@@ -41,6 +41,12 @@ envs pull
 
 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 +131,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,14 +174,36 @@ 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                                                   |
 | --------------------- | --------------------------------------------------------- |
 | `ENVSTASH_TOKEN`      | Use this token instead of the stored one — for CI         |
 | `ENVSTASH_HOST`       | Target another server (default `https://www.envstash.co`) |
+| `ENVSTASH_PORT`       | Target a dev server on localhost at this port             |
 | `ENVSTASH_CONFIG_DIR` | Where credentials live (default `~/.envstash`)            |
-| `ENVSTASH_DEV`        | Log in to a local dev server when one is running          |
+| `ENVSTASH_DEV`        | Look for a local dev server to log in to                  |
 | `ENVSTASH_DEBUG`      | Print stack traces on failure                             |
 | `NO_COLOR`            | Disable colour (also off automatically when piped)        |
 
@@ -157,16 +218,42 @@ checkout, and without this rule a repo could name a server and be handed your
 credential. If a repo pins a host you have not used, the CLI says so and tells
 you the `--host` to pass if you meant it.
 
-### Logging in to a local server
+### Working against a local server
+
+Every command takes `--port` as shorthand for a server on this machine, so
+`--port 3001` says what `--host http://localhost:3001` says:
+
+```bash
+envs status --port 3001
+envs pull --port 3001
+```
+
+`ENVSTASH_PORT=3001` does the same for a whole shell. Passing `--host` and
+`--port` together is refused rather than resolved — they are two ways of naming
+one server, and picking one silently is how a command ends up talking to the
+server you meant to exclude.
+
+`envs login` is deliberately not affected by any of this. **It signs in to
+`https://www.envstash.co` unless you say otherwise**, even if your last login
+was to a dev server: where the previous login went is not an instruction about
+where the next one should go.
+
+To sign in to a local server, name it — `envs login --port 3001` — or let the
+CLI find it:
+
+```bash
+envs login --dev
+```
 
-`envs login --dev` (or `ENVSTASH_DEV=1`) looks for an EnvStash dev server on
-ports 3000, 3001, 3002 and 3003 and logs in to the first one that answers, so the
-link it opens points at the server you are running rather than production.
-Production is the fallback when none answer, and an explicit `--host` always
-wins over detection.
+`--dev` (or `ENVSTASH_DEV=1`) looks for an EnvStash dev server on ports 3000,
+3001, 3002 and 3003 and logs in to the first one that answers. Production is the
+fallback when none answer, and an explicit `--host` or `--port` always wins over
+detection.
 
-A port is only accepted if it responds as an EnvStash server, so an unrelated
-process holding 3000 is skipped rather than logged in to.
+A port is only accepted by detection if it responds as an EnvStash server, so an
+unrelated process holding 3000 is skipped rather than logged in to. `--port`
+does not probe: naming a port is you being explicit, and that is not
+second-guessed.
 
 ## Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envstash-cli",
-  "version": "0.1.1",
+  "version": "0.3.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,6 +1,12 @@
 import { api } from '../api.mjs'
 import { getStoredEmail } from '../config.mjs'
-import { discoverEnvFiles, findRepoRoot, readLink, resolveProject, writeLink } from '../project.mjs'
+import {
+  discoverTrackedFiles,
+  findRepoRoot,
+  readLink,
+  resolveProject,
+  writeLink,
+} from '../project.mjs'
 import { requireHostToken, resolveHostFor } from '../session.mjs'
 import { out, pad, pluralize, style } from '../ui.mjs'
 
@@ -69,7 +75,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 +136,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/dev-host.mjs

@@ -8,6 +8,7 @@
  * mean "dev".
  */
 import { DEFAULT_HOST } from './config.mjs'
+import { CliError } from './ui.mjs'
 
 /**
  * The ports `scripts/dev-with-port.mjs` hands out, which are in turn the ports
@@ -82,3 +83,52 @@ export function isDevMode(flags) {
 
 /** The host used when dev mode finds nothing — production, the last resort. */
 export const FALLBACK_HOST = DEFAULT_HOST
+
+/**
+ * The host a `--port` (or `ENVSTASH_PORT`) asked for, or null when neither did.
+ *
+ * A port with no host can only mean a server on this machine, so it expands to
+ * the same `http://localhost:<port>` shape detection produces. It exists because
+ * the alternative for every non-login command was spelling out
+ * `--host http://localhost:3001` — long enough that people export ENVSTASH_HOST
+ * for the shell instead, and then forget it is set when they go back to
+ * production.
+ *
+ * Unlike detection this does not probe: naming a port is the developer being
+ * explicit, and second-guessing an explicit answer is how `--host` would behave
+ * if it checked too.
+ */
+export function resolvePortHost(flags) {
+  // `hasOwn` rather than a truthiness check: `--port` with nothing after it
+  // parses to undefined, and that is a mistake worth naming rather than a
+  // reason to fall through to the environment.
+  const fromFlag = Boolean(flags) && Object.hasOwn(flags, 'port')
+  const raw = fromFlag ? flags.port : process.env.ENVSTASH_PORT
+
+  if (!fromFlag && !raw) {
+    return null
+  }
+
+  return { host: `http://localhost:${parsePort(raw, fromFlag)}`, source: fromFlag ? 'flag' : 'env' }
+}
+
+/**
+ * A port is an integer in 1–65535 and nothing else.
+ *
+ * Refusing the rest matters more here than it looks: every value that slips
+ * through becomes a host, and a host that is quietly wrong fails later, as a
+ * connection error against a server the developer never meant to name.
+ */
+function parsePort(value, fromFlag) {
+  const text = String(value ?? '').trim()
+  const port = Number(text)
+
+  if (!text || !Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new CliError(
+      `${fromFlag ? '--port' : 'ENVSTASH_PORT'} needs a port number${text ? `, not "${text}"` : ''}.`,
+      { hint: 'For example: --port 3001' }
+    )
+  }
+
+  return port
+}

package/src/index.mjs

@@ -16,7 +16,10 @@ 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', '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 }
@@ -85,6 +88,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
@@ -136,6 +147,7 @@ export async function run(argv) {
   }
 
   try {
+    changeDirectory(flags)
     const code = await command.run(flags, rest)
     return finish(code ?? 0)
   } catch (error) {
@@ -166,6 +178,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,13 +238,19 @@ 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(`    --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')}`)
   out()
+  out(
+    `  ${style.dim('login always signs in to')} ${DEFAULT_HOST} ${style.dim('unless one of those says otherwise.')}`
+  )
+  out()
   out(`  ${style.bold('Environment')}`)
 
   const envPad =
@@ -265,9 +314,14 @@ const COMMAND_HELP = {
   login: [
     'Authorize this machine using a browser device code.',
     '',
+    'Signs in to production unless you say otherwise — a previous login to a dev',
+    'server does not change where the next one goes.',
+    '',
     '  envs login',
     '  envs login --no-browser     Print the URL instead of opening it',
     '  envs login --host <url>     Sign in to another server',
+    '  envs login --port 3001      Sign in to a dev server on localhost:3001',
+    '  envs login --dev            Find a local dev server and sign in to it',
   ],
   logout: [
     'Revoke this machine’s token and remove it locally.',

package/src/manifest.mjs

@@ -51,13 +51,17 @@ export const CLI_ALIASES = Object.fromEntries(
 export const CLI_ENV_VARS = [
   { name: 'ENVSTASH_TOKEN', purpose: () => 'Use this token instead of the stored one — for CI' },
   { name: 'ENVSTASH_HOST', purpose: host => `Target another server (default ${host})` },
+  {
+    name: 'ENVSTASH_PORT',
+    purpose: () => 'Target a dev server on localhost at this port (same as --port)',
+  },
   {
     name: 'ENVSTASH_CONFIG_DIR',
     purpose: () => 'Where credentials live (default ~/.envstash)',
   },
   {
     name: 'ENVSTASH_DEV',
-    purpose: () => 'Log in to a local dev server when one is running (same as --dev)',
+    purpose: () => 'Look for a local dev server to log in to (same as --dev)',
   },
   { name: 'ENVSTASH_DEBUG', purpose: () => 'Print stack traces on failure' },
   { name: 'NO_COLOR', purpose: () => 'Disable colour (also off automatically when piped)' },

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/session.mjs

@@ -1,6 +1,7 @@
-import { requireToken, resolveHost } from './config.mjs'
-import { detectDevHost, isDevMode } from './dev-host.mjs'
+import { DEFAULT_HOST, requireToken, resolveHost } from './config.mjs'
+import { detectDevHost, isDevMode, resolvePortHost } from './dev-host.mjs'
 import { findRepoRoot, readLink } from './project.mjs'
+import { CliError } from './ui.mjs'
 
 /**
  * Resolve host and token together.
@@ -18,6 +19,39 @@ export function requireHostToken(flags) {
   return { host, token: requireToken(host, { allowEnvToken: source !== 'link' }) }
 }
 
+/**
+ * The host the developer named for this command, or null when they named none.
+ *
+ * The ladder is the usual one — what you typed beats what your shell exported —
+ * with `--port` sitting beside `--host` at each rung, because they are two ways
+ * of saying the same thing. Passing both is therefore a contradiction rather
+ * than a precedence question, and it is refused: silently picking one is how a
+ * command ends up talking to a server the developer explicitly excluded.
+ */
+export function resolveExplicitHost(flags) {
+  const port = resolvePortHost(flags)
+
+  if (flags?.host && port?.source === 'flag') {
+    throw new CliError(`--host and --port both name a server: ${flags.host} and ${port.host}.`, {
+      hint: 'Pass one of them.',
+    })
+  }
+
+  if (flags?.host) {
+    return { host: resolveHost(flags.host), source: 'flag' }
+  }
+
+  if (port?.source === 'flag') {
+    return port
+  }
+
+  if (process.env.ENVSTASH_HOST) {
+    return { host: resolveHost(undefined), source: 'env' }
+  }
+
+  return port
+}
+
 /**
  * Resolve the host and say where the decision came from.
  *
@@ -27,8 +61,10 @@ export function requireHostToken(flags) {
  * less trust.
  */
 export function resolveHostSource(flags) {
-  if (flags?.host || process.env.ENVSTASH_HOST) {
-    return { host: resolveHost(flags?.host), source: flags?.host ? 'flag' : 'env' }
+  const explicit = resolveExplicitHost(flags)
+
+  if (explicit) {
+    return explicit
   }
 
   try {
@@ -64,18 +100,28 @@ export function isLinkChosenHost(flags, host) {
 /**
  * Host for an interactive login.
  *
- * The usual precedence with one step inserted: in dev mode a running local
- * server beats the stored default, so `pnpm cli:dev login` opens the server the
- * developer is running. An explicit `--host` or `ENVSTASH_HOST` still wins over
- * detection — asking for a specific server should never be second-guessed — and
- * production remains the last resort when no dev server answers.
+ * Login does not inherit the stored default the way every other command does,
+ * and that is the point: the stored default is wherever the *last* login went,
+ * so one `pnpm cli:dev login` used to make every later `pnpm envs login` sign in
+ * to localhost — which looks like it worked, right up to the point where a
+ * production command finds no credential. Production is the default here, and
+ * reaching a dev server is something you ask for.
+ *
+ * Above that: in dev mode a running local server beats production, so
+ * `pnpm cli:dev login` opens the server the developer is running. An explicit
+ * `--host`, `--port`, or `ENVSTASH_HOST` wins over detection — asking for a
+ * specific server should never be second-guessed. A host this repo's link file
+ * pinned still applies, since that is a deliberate per-repo choice, and
+ * `login` already refuses one it has never signed in to.
  *
  * `onDevHost` reports what detection found so the command can say so. Deciding
  * and printing are split because the decision is what the tests care about.
  */
 export async function resolveLoginHost(flags, { onDevHost } = {}) {
-  if (flags?.host || process.env.ENVSTASH_HOST) {
-    return resolveHost(flags?.host)
+  const explicit = resolveExplicitHost(flags)
+
+  if (explicit) {
+    return explicit.host
   }
 
   if (isDevMode(flags)) {
@@ -88,5 +134,7 @@ export async function resolveLoginHost(flags, { onDevHost } = {}) {
     }
   }
 
-  return resolveHostFor(flags)
+  const resolved = resolveHostSource(flags)
+
+  return resolved.source === 'link' ? resolved.host : DEFAULT_HOST
 }

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)