envstash-cli 0.8.0 → 0.10.0

package/README.md

@@ -46,6 +46,7 @@ envs sync
 | `push`    | Send local files to the cloud                        |
 | `sync`    | Reconcile both directions at once, keeping every key |
 | `remove`  | Delete files from the cloud (local copies stay)      |
+| `config`  | Show the settings in effect and where each came from |
 | `version` | Show the CLI version and its environment             |
 
 Run `envs help <command>` for details on any one of them.
@@ -119,11 +120,10 @@ definition and therefore has no undo:
   file are left alone, so pushing a partial `.env` cannot destroy a teammate's
   key. Use `--prune` when you do want the cloud to mirror local exactly.
 - **`push` lists new files before uploading them.** Any file that is not in the
-  cloud yet is shown, with its size, before the first upload. Files that
+  cloud yet is shown, with its size, before the first upload, and files that
   discovery found — not named on the command line and not listed in
-  `.envstash.json` — need a yes: `push` asks on a terminal, and anywhere else
-  (CI, a pipe) it stops unless you pass `--yes` (`-y`). Once a file is in the
-  cloud, later pushes of it go through without asking.
+  `.envstash.json` — are marked `(discovered)`. They are then uploaded. To be
+  asked first, turn on [`confirmNewFiles`](#settings).
 - **`diff` masks values**, showing at most the first 4 characters and the
   length, and nothing at all of a value 12 characters or shorter. Use
   `--show-values` to reveal them.
@@ -254,7 +254,8 @@ files to track — and it is what lets a teammate clone the repo and run
 
 Without a link file the CLI guesses the project from your git remote's repo
 name and discovers `.env*` files in the repo root, plus files in `.config/`
-(see below). Dotenv files ending in `.example`, `.sample`, `.template`, and
+and `.agents/` (see below). That list is the default, and
+[`discover`](#settings) changes it. Dotenv files ending in `.example`, `.sample`, `.template`, and
 `.dist` are ignored, since those are meant to be committed and hold placeholder
 values.
 
@@ -288,8 +289,40 @@ 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.
+by hand. The scan covers each discovered directory and everything under it;
+files anywhere else are declared explicitly.
+
+### Files in `.agents/`
+
+`.agents/` is where a repo keeps what its AI coding agents read — skills, rules,
+per-tool settings. When the directory exists it is discovered the same way as
+`.config/`, with two differences:
+
+- **Documents are kept.** Skills and rules are markdown, so the rule that keeps
+  a README out of `.config/` does not apply.
+- **It is never added to `.gitignore` for you.** Plenty of repos commit
+  `.agents/`, and ignoring it on the way past would make the next `git add -A`
+  silently leave it behind.
+
+Git-ignore is still the gate, so there are three cases:
+
+| `.agents/` is…                | What `push` and `sync` do                         |
+| ----------------------------- | ------------------------------------------------- |
+| git-ignored                   | Sync its files                                    |
+| committed                     | Nothing — git already carries it                  |
+| neither ignored nor committed | Nothing, and say so, so you can pick one of those |
+
+A `.agents` that is a symlink (to `.claude`, say) is skipped, like every other
+link.
+
+### Choosing what is discovered
+
+Discovery only decides the file list for a repo that has none of its own. Once
+`.envstash.json` lists `files`, that list is used as written — add
+`.agents/…` paths to it by hand, or remove `files` to go back to discovery.
+
+To change the defaults on this machine, set [`discover`](#settings). Run
+`envs config` to see the list in effect and the files it currently finds.
 
 Monorepos can track nested paths by listing them explicitly:
 
@@ -321,15 +354,15 @@ 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`        | 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)        |
+| 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 and settings live (default `~/.envstash`) |
+| `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)          |
 
 In CI, set `ENVSTASH_TOKEN` from your platform's secret store **and set
 `ENVSTASH_HOST`**, then run `envs pull` — no interactive login required.
@@ -342,6 +375,45 @@ 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.
 
+### Settings
+
+Preferences for this machine live in `~/.envstash/settings.json` — a separate
+file from `config.json`, which holds your tokens and is not meant to be edited
+by hand. The file is optional; create it to change a default.
+
+```json
+{
+  "confirmNewFiles": true,
+  "discover": [".env*", ".config", ".agents"]
+}
+```
+
+- **`confirmNewFiles`** (default `false`) — ask before `push` or `sync` uploads
+  a file that discovery found for the first time.
+- **`discover`** (default `[".env*", ".config", ".agents"]`) — what is synced in
+  a repo that does not list its own files.
+
+`discover` **replaces** the default list, so leaving an entry out turns it off:
+`[".env*", ".config"]` stops syncing `.agents/`, and `[]` discovers nothing.
+`".env*"` means the dotenv files in the repo root. Any other entry is a
+directory inside the repo, whose git-ignored files are synced — add `".claude"`
+to carry local agent settings, for example. `.git`, `node_modules`, and paths
+that leave the repo are refused.
+
+It lives here rather than in `.envstash.json` on purpose: that file arrives
+with a clone, and a repo should not get to choose which of your directories are
+uploaded. Taking a directory out of `discover` stops new files being found; files
+already in the cloud keep syncing until you `envs rm` them.
+
+`envs config` prints every setting in effect and whether it came from this file
+or is a default, along with the server, account, and this repo's project and
+files. It never prints a token.
+
+With `confirmNewFiles` on, `push` and `sync` ask on a terminal, and anywhere
+else (CI, a pipe) they stop unless you pass `--yes` (`-y`). Files you named on
+the command line, files listed in `.envstash.json`, and files already in the
+cloud are never asked about.
+
 ### Working against a local server
 
 Every command takes `--port` as shorthand for a server on this machine, so

package/package.json

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

package/src/commands/misc.mjs

@@ -1,19 +1,21 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { api } from '../api.mjs'
-import { configDir, getStoredEmail } from '../config.mjs'
+import { configDir, configPath, getStoredEmail, getToken } from '../config.mjs'
 import {
   discoverTrackedFiles,
   findRepoRoot,
+  LINK_FILE,
   readLink,
   resolveProject,
   writeLink,
 } from '../project.mjs'
 import { requireHostToken, resolveHostFor, resolveHostSource } from '../session.mjs'
+import { DEFAULT_SETTINGS, readSettings, settingsPath } from '../settings.mjs'
 import { out, pad, pluralize, sanitize, style } from '../ui.mjs'
-import { announceIgnoredSecretDir } from './push.mjs'
+import { announceDiscoveryDirs } from './push.mjs'
 
 /**
  * `envs version` — the version, and the environment it would act in.
@@ -76,6 +78,120 @@ function sourceLabel(source) {
   )
 }
 
+/**
+ * `envs config` — every setting in effect, and where each one came from.
+ *
+ * The CLI's behaviour is decided in four places — `settings.json`, the
+ * credential file, the environment, and the repo's link file — and none of them
+ * is on screen when a command does something unexpected. This prints the
+ * resolved answer from all four, read through the same functions the sync
+ * commands use, so it cannot describe a configuration they would not act on.
+ *
+ * Never the token: only whether there is one, and which place supplied it.
+ * Nothing here touches the network, so it works signed out and offline.
+ */
+export async function config(flags) {
+  const settings = readSettings()
+  const { host, source } = resolveHostSource(flags)
+  const repoRoot = findRepoRoot()
+  const link = readLink(repoRoot)
+  const project = resolveProject(repoRoot, flags.project)
+  const linked = Boolean(link?.files?.length)
+
+  const details = {
+    configDir: configDir(),
+    settingsFile: { path: settingsPath(), exists: existsSync(settingsPath()) },
+    settings,
+    // Which settings the file changed, so a default is never mistaken for a choice.
+    changed: Object.keys(settings).filter(
+      key => JSON.stringify(settings[key]) !== JSON.stringify(DEFAULT_SETTINGS[key])
+    ),
+    credentialsFile: { path: configPath(), exists: existsSync(configPath()) },
+    host,
+    hostSource: source,
+    account: getStoredEmail(host),
+    token: tokenSource(host, source),
+    repo: {
+      root: repoRoot,
+      linkFile: link ? LINK_FILE : null,
+      project: project.name,
+      projectSource: project.source,
+      files: linked ? link.files : discoverTrackedFiles(repoRoot, settings.discover),
+      filesSource: linked ? 'link' : 'discovery',
+    },
+  }
+
+  if (flags.json) {
+    out(JSON.stringify(details, null, 2))
+    return 0
+  }
+
+  const width = 18
+  const row = (label, value, note) =>
+    out(`  ${pad(label, width)}${value}${note ? style.dim(`  (${note})`) : ''}`)
+  const origin = key => (details.changed.includes(key) ? 'settings.json' : 'default')
+
+  out()
+  out(`  ${style.bold('Settings')} ${style.dim(details.settingsFile.path)}`)
+  if (!details.settingsFile.exists) {
+    out(`  ${style.dim('No settings file — every value below is a default.')}`)
+  }
+  out()
+  for (const [key, value] of Object.entries(settings)) {
+    row(key, Array.isArray(value) ? value.join(', ') || style.dim('nothing') : value, origin(key))
+  }
+
+  out()
+  out(`  ${style.bold('Server')}`)
+  out()
+  row('host', host, sourceLabel(source))
+  row('account', details.account ?? style.dim('not signed in'))
+  row('token', TOKEN_LABELS[details.token])
+  row('credentials', style.dim(details.credentialsFile.path))
+
+  out()
+  out(`  ${style.bold('This repo')} ${style.dim(repoRoot)}`)
+  out()
+  row('project', project.name, PROJECT_LABELS[project.source])
+  row('link file', link ? LINK_FILE : style.dim('none'))
+  row(
+    'files',
+    details.repo.files.length ? pluralize(details.repo.files.length, 'file') : style.dim('none'),
+    linked ? `listed in ${LINK_FILE}` : 'found by discovery'
+  )
+  for (const file of details.repo.files) {
+    out(`    ${style.dim('·')} ${file}`)
+  }
+  out()
+
+  return 0
+}
+
+/**
+ * Where this command's token would come from, without revealing it. Mirrors
+ * `requireHostToken`: the environment's token is not spent on a host the link
+ * file chose.
+ */
+function tokenSource(host, hostSource) {
+  if (hostSource !== 'link' && process.env.ENVSTASH_TOKEN) {
+    return 'env'
+  }
+
+  return getToken(host, { allowEnvToken: false }) ? 'stored' : 'none'
+}
+
+const TOKEN_LABELS = {
+  env: 'from ENVSTASH_TOKEN',
+  stored: 'stored on this machine',
+  none: 'none',
+}
+
+const PROJECT_LABELS = {
+  flag: 'from --project',
+  link: `from ${LINK_FILE}`,
+  guess: 'guessed from the repo name',
+}
+
 /** `envs whoami` — which account this machine is signed in as. */
 export async function whoami(flags) {
   const { host, token } = await requireHostToken(flags)
@@ -145,9 +261,11 @@ export async function init(flags, args) {
 
   // Before discovery, so a not-yet-ignored .config/ lands in the link file
   // this init writes rather than being silently absent from it.
-  announceIgnoredSecretDir(repoRoot)
+  announceDiscoveryDirs(repoRoot, { discovering: !existing?.files?.length })
 
-  const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
+  const files = existing?.files?.length
+    ? existing.files
+    : discoverTrackedFiles(repoRoot, readSettings().discover)
   const path = writeLink(repoRoot, {
     project: name,
     files,
@@ -209,9 +327,11 @@ export async function link(flags, args) {
   await api.projectStatus(host, token, name)
 
   // Same moment as in init: discovery is about to decide the link file's list.
-  announceIgnoredSecretDir(repoRoot)
+  announceDiscoveryDirs(repoRoot, { discovering: !existing?.files?.length })
 
-  const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
+  const files = existing?.files?.length
+    ? existing.files
+    : discoverTrackedFiles(repoRoot, readSettings().discover)
   const path = writeLink(repoRoot, { project: name, files, host: existing?.host ?? null })
 
   out()

package/src/commands/push.mjs

@@ -9,22 +9,57 @@ import {
   resolveFileNames,
   SHARED_SCOPE,
 } from '../context.mjs'
-import { ensureSecretDirIgnored, SECRET_FILE_DIR } from '../project.mjs'
+import {
+  ensureSecretDirIgnored,
+  ENV_FILES_TARGET,
+  lacksIgnoreRule,
+  SECRET_FILE_DIR,
+} from '../project.mjs'
 import { resolveRepoFile } from '../repo-path.mjs'
+import { readSettings } from '../settings.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
 import { CliError, confirm, isInteractive, out, pad, pluralize, style } from '../ui.mjs'
 
-/** Say that .gitignore was edited — quietly rewriting a user's file is worse. */
-export function announceIgnoredSecretDir(repoRoot) {
-  if (!ensureSecretDirIgnored(repoRoot)) {
-    return
+/**
+ * Get the discovered directories ready, and say what was done or left undone.
+ *
+ * Discovery only offers files git ignores, so a directory with contents that
+ * nothing tracks and nothing ignores is carried by neither git nor envstash.
+ * For `.config/` that is closed by adding the ignore rule — and saying so, since
+ * quietly rewriting a user's file is worse. For any other directory it is only
+ * pointed out: `.agents/` is committed in plenty of repos, and ignoring it on
+ * the way past would make the next `git add -A` silently leave it behind.
+ *
+ * A directory the developer took out of `discover` is not touched or mentioned.
+ * `discovering` is false when this run's files were chosen by name or by the
+ * link file: discovery is not deciding anything then, so there is nothing to
+ * point out.
+ */
+export function announceDiscoveryDirs(repoRoot, { discovering = true } = {}) {
+  const dirs = readSettings().discover.filter(target => target !== ENV_FILES_TARGET)
+
+  if (dirs.includes(SECRET_FILE_DIR) && ensureSecretDirIgnored(repoRoot)) {
+    out()
+    out(
+      `  ${style.green('+')} Added ${style.bold(`${SECRET_FILE_DIR}/`)} to .gitignore ` +
+        style.dim('— secrets sync through EnvStash, not git')
+    )
   }
 
-  out()
-  out(
-    `  ${style.green('+')} Added ${style.bold(`${SECRET_FILE_DIR}/`)} to .gitignore ` +
-      style.dim('— secrets sync through EnvStash, not git')
-  )
+  const leftToGit = discovering
+    ? dirs.filter(dir => dir !== SECRET_FILE_DIR && lacksIgnoreRule(repoRoot, dir))
+    : []
+
+  if (leftToGit.length > 0) {
+    out()
+  }
+
+  for (const dir of leftToGit) {
+    out(
+      `  ${style.yellow('!')} ${style.bold(`${dir}/`)} is not git-ignored, so it is not synced ` +
+        style.dim('— add it to .gitignore to sync it through EnvStash, or commit it')
+    )
+  }
 }
 
 /**
@@ -57,7 +92,9 @@ export async function push(flags, args) {
   // this very push rather than the next one. Not under --dry-run: a preview
   // that edits files is not a preview.
   if (!flags['dry-run']) {
-    announceIgnoredSecretDir(context.repoRoot)
+    announceDiscoveryDirs(context.repoRoot, {
+      discovering: args.length === 0 && !context.link?.files?.length,
+    })
   }
 
   const cloudFiles = await fetchCloudFiles(context, scope)
@@ -183,18 +220,25 @@ export async function push(flags, args) {
 }
 
 /**
- * Show — and for discovered files, ask about — every file this push would
- * create in the cloud, before the first byte goes up.
+ * Show every file this push would create in the cloud, before the first byte
+ * goes up — and, when the developer has asked to be asked, get a yes for the
+ * ones discovery found.
  *
  * Discovery sweeps root `.env*` files and everything git-ignored under
- * `.config/`, recursively, and used to upload the lot and only then list it. A
- * gcloud token cache or a stray SQLite file was in the cloud before the
- * developer saw its name. A file already in the cloud, named on the command
- * line, or listed in `.envstash.json` was chosen by someone; a file discovery
- * found for the first time was not, so that is the set that needs a yes.
+ * `.config/` and `.agents/`, recursively, and used to upload the lot and only
+ * then list it.
+ * The list now always comes first, marking which files were discovered.
+ *
+ * Uploading them is the default: a developer who runs `envs push` in their own
+ * repo means "send my files up", and a question on every new file trained the
+ * answer to be `y`. Setting `"confirmNewFiles": true` in
+ * `~/.envstash/settings.json` restores the gate. A file already in the cloud,
+ * named on the command line, or listed in `.envstash.json` was chosen by
+ * someone; a file discovery found for the first time was not, so that is the
+ * set the gate asks about.
  *
- * Asked on a terminal; refused without `--yes` anywhere else, since a CI job
- * cannot answer and silently uploading is the thing being fixed.
+ * With the gate on: asked on a terminal; refused without `--yes` anywhere
+ * else, since a CI job cannot answer.
  *
  * `envs sync` uploads new files too, and runs the same gate — `command` only
  * changes which command name the messages tell the developer to re-run.
@@ -224,6 +268,10 @@ export async function confirmNewFiles(flags, context, args, comparison, { comman
     return
   }
 
+  if (!readSettings().confirmNewFiles) {
+    return
+  }
+
   const count = pluralize(discovered.length, 'discovered file')
 
   if (isInteractive()) {

package/src/commands/sync.mjs

@@ -15,7 +15,7 @@ import { resolveRepoFile } from '../repo-path.mjs'
 import { compareProject } from '../status.mjs'
 import { conflictExitCode, isBlocked, isChanging, planSync, PREFER, SYNC_ACTION } from '../sync.mjs'
 import { CliError, out, pad, pluralize, sanitize, style } from '../ui.mjs'
-import { announceIgnoredSecretDir, confirmNewFiles, fetchCloudFiles, pushOneBlob } from './push.mjs'
+import { announceDiscoveryDirs, confirmNewFiles, fetchCloudFiles, pushOneBlob } from './push.mjs'
 
 /**
  * `envs sync` — reconcile this repo with the cloud, in both directions at once.
@@ -53,7 +53,9 @@ export async function sync(flags, args) {
   // .config/ is covered by this run rather than the next one, and never under
   // --dry-run, because a preview that edits files is not a preview.
   if (!flags['dry-run']) {
-    announceIgnoredSecretDir(context.repoRoot)
+    announceDiscoveryDirs(context.repoRoot, {
+      discovering: args.length === 0 && !context.link?.files?.length,
+    })
   }
 
   const cloudFiles = await fetchCloudFiles(context, scope)
@@ -84,9 +86,9 @@ export async function sync(flags, args) {
   const plans = planSync(comparison, { prefer })
   const byName = new Map(comparison.map(file => [file.name, file]))
 
-  // The same gate `push` puts in front of a file discovery found on its own.
-  // Sync uploads new files too, and "it synced" is no more of an excuse for a
-  // gcloud token cache reaching the cloud unasked than "it pushed" was.
+  // The same listing — and, when `confirmNewFiles` is set, the same gate —
+  // `push` puts in front of a file discovery found on its own. Sync uploads
+  // new files too.
   await confirmNewFiles(flags, context, args, comparison, { command: 'sync' })
 
   out()

package/src/context.mjs

@@ -5,6 +5,7 @@ import { parseEnvFile } from './env-file.mjs'
 import { discoverTrackedFiles, findRepoRoot, readLink, resolveProject } from './project.mjs'
 import { findSymlink, resolveInsideRepo, resolveRepoFile } from './repo-path.mjs'
 import { requireHostToken } from './session.mjs'
+import { readSettings } from './settings.mjs'
 import { errOut, pluralize, style } from './ui.mjs'
 
 /**
@@ -35,8 +36,9 @@ export async 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 what discovery finds — root `.env*` files plus git-ignored
- * files in `.config/` — and whatever the cloud holds. Those inferred names skip
+ * fall back to the union of what discovery finds — by default root `.env*` files plus
+ * git-ignored files in `.config/` and `.agents/`; the `discover` setting says otherwise —
+ * and whatever the cloud holds. Those inferred names skip
  * symbolic links with a warning rather than refusing (see `skipSymlinks`);
  * `sink` is `'write'` for `pull`, so the warning says the file is not written.
  */
@@ -49,7 +51,10 @@ export function resolveFileNames({ repoRoot, link, cloudFiles, requested, sink =
     return check([...new Set(link.files)].sort())
   }
 
-  const names = new Set([...discoverTrackedFiles(repoRoot), ...cloudFiles.map(file => file.name)])
+  const names = new Set([
+    ...discoverTrackedFiles(repoRoot, readSettings().discover),
+    ...cloudFiles.map(file => file.name),
+  ])
 
   return skipSymlinks(repoRoot, check([...names].sort()), sink)
 }

package/src/index.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { abandonedConnection } from './api.mjs'
 import { diff } from './commands/diff.mjs'
 import { login, logout } from './commands/login.mjs'
-import { init, link, list, version as versionCommand, whoami } from './commands/misc.mjs'
+import { config, init, link, list, version as versionCommand, whoami } from './commands/misc.mjs'
 import { pull } from './commands/pull.mjs'
 import { push } from './commands/push.mjs'
 import { remove } from './commands/remove.mjs'
@@ -38,6 +38,7 @@ const HANDLERS = {
   push,
   sync,
   remove,
+  config,
   version: versionCommand,
 }
 
@@ -281,14 +282,16 @@ function printHelp(topic) {
   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, version)')}`
+    `    --json             ${style.dim('Machine-readable output (status, list, whoami, config, version)')}`
   )
   out(
     `    --exit-zero        ${style.dim('Always exit 0, even when out of sync (status, diff, sync)')}`
   )
   out(`    --prefer <side>    ${style.dim('Resolve conflicts as "local" or "cloud" (sync)')}`)
   out(`    --dry-run          ${style.dim('Show what would happen (pull, push, sync, remove)')}`)
-  out(`    -y, --yes          ${style.dim('Upload newly discovered files without asking (push)')}`)
+  out(
+    `    -y, --yes          ${style.dim('Skip the new-file question, if you turned it on (push, sync)')}`
+  )
   out(
     `    --shared           ${style.dim('Target your account-wide shared files (pull, push, sync, remove)')}`
   )
@@ -378,9 +381,10 @@ const COMMAND_HELP = {
     'Keys in the cloud that are absent locally are left alone unless --prune is',
     'given, so pushing a partial .env cannot delete a teammate’s key.',
     '',
-    'Files that would be new in the cloud are listed before anything uploads.',
-    'Ones found by discovery — not named, not in .envstash.json — need a yes:',
-    'asked on a terminal, --yes (-y) anywhere else.',
+    'Files that would be new in the cloud are listed before anything uploads,',
+    'then uploaded. To be asked first about ones found by discovery — not',
+    'named, not in .envstash.json — put { "confirmNewFiles": true } in',
+    '~/.envstash/settings.json; --yes (-y) then answers for one run.',
     '',
     '--shared sends the named files to your account-wide shared files — for',
     'credentials that follow you across projects, like a global .npmrc. Pull',
@@ -388,7 +392,7 @@ const COMMAND_HELP = {
     '',
     '  envs push',
     '  envs push --dry-run',
-    '  envs push --yes             Upload newly discovered files without asking',
+    '  envs push --yes             Skip the new-file question, if you turned it on',
     '  envs push --prune',
     '  envs push --shared .npmrc',
   ],
@@ -430,6 +434,22 @@ 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'],
+  config: [
+    'Print every setting in effect and where each one came from: your',
+    '~/.envstash/settings.json, the server and account commands would use, and',
+    'this repo’s project and files. Tokens are never printed. Works offline.',
+    '',
+    'To change what is synced by default, set "discover" in settings.json. It',
+    'replaces the default list, so leave an entry out to turn it off:',
+    '',
+    '  { "discover": [".env*", ".config", ".agents"] }',
+    '',
+    '".env*" is the dotenv files in the repo root; anything else is a directory',
+    'whose git-ignored files are synced.',
+    '',
+    '  envs config',
+    '  envs config --json',
+  ],
   version: [
     'Show the version, runtime, install path, and which server commands would',
     'talk to. --version and -v print the bare version for scripts.',

package/src/manifest.mjs

@@ -29,6 +29,7 @@ export const CLI_COMMANDS = [
   { name: 'push', summary: 'Send local files to the cloud' },
   { name: 'sync', summary: 'Reconcile both directions at once, keeping every key' },
   { name: 'remove', summary: 'Delete files from the cloud (local copies stay)', aliases: ['rm'] },
+  { name: 'config', summary: 'Show the settings in effect and where each came from' },
   { name: 'version', summary: 'Show the CLI version and its environment' },
 ]
 

package/src/project.mjs

@@ -202,6 +202,26 @@ export function discoverEnvFiles(repoRoot) {
  */
 export const SECRET_FILE_DIR = '.config'
 
+/**
+ * Where a repo keeps what its AI coding agents read — skills, rules, per-tool
+ * settings. Not a credential, but the same population as one: files a developer
+ * needs on every machine and, when the repo ignores them, cannot get from git.
+ */
+export const AGENTS_DIR = '.agents'
+
+/**
+ * The discovery target that means "dotenv files in the repo root". Every other
+ * target names a directory; this one names the scan in `discoverEnvFiles`, which
+ * is a naming rule rather than a place.
+ */
+export const ENV_FILES_TARGET = '.env*'
+
+/**
+ * What discovery looks at when the developer has not said otherwise — the
+ * `discover` list in `~/.envstash/settings.json` replaces it wholesale.
+ */
+export const DEFAULT_DISCOVER = [ENV_FILES_TARGET, SECRET_FILE_DIR, AGENTS_DIR]
+
 /**
  * Which of `names` git ignores, as a Set.
  *
@@ -251,7 +271,9 @@ const DOCUMENT_SUFFIXES = [
 ]
 
 /**
- * Discover files in `.config/` — all of them, except documents.
+ * Discover the files in one directory that git ignores.
+ *
+ * `.config/` is where this started, and the reasoning below is written for it:
  *
  * 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
@@ -265,8 +287,12 @@ const DOCUMENT_SUFFIXES = [
  * 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)
+export function discoverDirFiles(repoRoot, dir) {
+  const directory = join(repoRoot, dir)
+  // Only `.config/` drops documents. There a README is noise beside the keys;
+  // in `.agents/` the markdown *is* the content, and a directory the developer
+  // listed themselves is taken at their word.
+  const skipDocuments = dir === SECRET_FILE_DIR
   let entries
 
   try {
@@ -277,15 +303,18 @@ export function discoverSecretFiles(repoRoot) {
 
   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)))
+    .map(entry => `${dir}/${entry.split(sep).join('/')}`)
+    .filter(
+      name =>
+        !skipDocuments || !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 {
-        // A link anywhere on the path — `.config` itself, a subdirectory, or the
-        // file — could point outside the repo, so it is not offered.
+        // A link anywhere on the path — the directory itself, a subdirectory, or
+        // the file — could point outside the repo, so it is not offered.
         if (findSymlink(repoRoot, name)) {
           return false
         }
@@ -304,26 +333,25 @@ export function discoverSecretFiles(repoRoot) {
   return candidates.filter(name => ignored.has(name)).sort()
 }
 
+/** Discover files in `.config/` — all of them, except documents. */
+export function discoverSecretFiles(repoRoot) {
+  return discoverDirFiles(repoRoot, SECRET_FILE_DIR)
+}
+
 /**
- * Make sure `.config/` is git-ignored before discovery asks about it.
- *
- * Being ignored is discovery's signal for "secret", which makes an unignored
- * `.config/` silently invisible to `envs push` — a real footgun: the developer
- * sees a directory full of credentials and a push that ignores them, with
- * nothing saying why. Rather than documenting that, push and init close it:
- * when the directory has contents, nothing in it is tracked by git, and it is
- * not already ignored, `.config/` is added to .gitignore. A `.config/` with
- * tracked files is a repo that commits configuration there on purpose, and is
- * left alone.
+ * True when `dir` has contents that neither git nor envstash will carry:
+ * nothing in it is tracked, and nothing ignores it.
  *
- * Returns true when .gitignore was changed — the caller must say so out loud,
- * because a CLI editing a file it does not own should never do it silently.
+ * Being ignored is discovery's signal, which makes a directory in this state
+ * silently invisible to `envs push`. What to do about it differs by directory —
+ * see `ensureSecretDirIgnored` and the note `push` prints for the others — but
+ * the question is the same one.
  */
-export function ensureSecretDirIgnored(repoRoot) {
+export function lacksIgnoreRule(repoRoot, dir) {
   let entries
 
   try {
-    entries = readdirSync(join(repoRoot, SECRET_FILE_DIR))
+    entries = readdirSync(join(repoRoot, dir))
   } catch {
     return false
   }
@@ -337,20 +365,40 @@ export function ensureSecretDirIgnored(repoRoot) {
   let tracked
 
   try {
-    tracked = runGit(['ls-files', '--', SECRET_FILE_DIR], { cwd: repoRoot }).trim()
+    tracked = runGit(['ls-files', '--', dir], { cwd: repoRoot }).trim()
   } catch {
     return false
   }
 
+  // Tracked content means the repo commits this directory on purpose.
   if (tracked !== '') {
     return false
   }
 
   // A synthetic name, so one question covers the directory: any rule broad
   // enough to ignore this probe ignores everything discovery would find.
-  const probe = `${SECRET_FILE_DIR}/envstash-ignore-probe`
+  const probe = `${dir}/envstash-ignore-probe`
+
+  return !gitIgnoredNames(repoRoot, [probe]).has(probe)
+}
 
-  if (gitIgnoredNames(repoRoot, [probe]).has(probe)) {
+/**
+ * Make sure `.config/` is git-ignored before discovery asks about it.
+ *
+ * Being ignored is discovery's signal for "secret", which makes an unignored
+ * `.config/` silently invisible to `envs push` — a real footgun: the developer
+ * sees a directory full of credentials and a push that ignores them, with
+ * nothing saying why. Rather than documenting that, push and init close it:
+ * when the directory has contents, nothing in it is tracked by git, and it is
+ * not already ignored, `.config/` is added to .gitignore. A `.config/` with
+ * tracked files is a repo that commits configuration there on purpose, and is
+ * left alone.
+ *
+ * Returns true when .gitignore was changed — the caller must say so out loud,
+ * because a CLI editing a file it does not own should never do it silently.
+ */
+export function ensureSecretDirIgnored(repoRoot) {
+  if (!lacksIgnoreRule(repoRoot, SECRET_FILE_DIR)) {
     return false
   }
 
@@ -379,9 +427,21 @@ export function ensureSecretDirIgnored(repoRoot) {
   return true
 }
 
-/** Everything auto-discovery offers to track: root dotenv files, then `.config/` files. */
-export function discoverTrackedFiles(repoRoot) {
-  return [...discoverEnvFiles(repoRoot), ...discoverSecretFiles(repoRoot)]
+/**
+ * Everything auto-discovery offers to track, target by target in the order
+ * given: root dotenv files for `.env*`, the git-ignored files of each directory
+ * otherwise.
+ *
+ * `targets` is passed in rather than read from settings here, so this stays a
+ * function of the repo alone; callers hand it `readSettings().discover`.
+ */
+export function discoverTrackedFiles(repoRoot, targets = DEFAULT_DISCOVER) {
+  const names = targets.flatMap(target =>
+    target === ENV_FILES_TARGET ? discoverEnvFiles(repoRoot) : discoverDirFiles(repoRoot, target)
+  )
+
+  // Two targets can overlap (`.config` and `.config/gcloud`); each file once.
+  return [...new Set(names)]
 }
 
 /**

package/src/settings.mjs

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { configDir } from './config.mjs'
+import { DEFAULT_DISCOVER, ENV_FILES_TARGET } from './project.mjs'
+import { isSafeRepoPath } from './repo-path.mjs'
+import { CliError } from './ui.mjs'
+
+/**
+ * Preferences for this machine, next to — and deliberately not inside — the
+ * credential file. `config.json` holds every token and is rewritten by login
+ * and logout; a file meant to be edited by hand should not be one where a
+ * stray comma signs the developer out of everything.
+ *
+ * Per machine rather than per repo: `.envstash.json` travels with a clone, and
+ * how much a developer wants to be asked — or which of their directories get
+ * swept up — is theirs to decide, not the repo's. A cloned repo that could say
+ * "also discover this directory" would be choosing what leaves the machine.
+ *
+ * {
+ *   "confirmNewFiles": true,
+ *   "discover": [".env*", ".config"]
+ * }
+ */
+export const DEFAULT_SETTINGS = Object.freeze({
+  /** Ask before uploading a file that discovery found for the first time. */
+  confirmNewFiles: false,
+  /**
+   * What discovery looks at in a repo with no file list of its own: `.env*` for
+   * root dotenv files, and directories whose git-ignored files are offered.
+   * Replaces the default list rather than adding to it, so leaving an entry out
+   * is how it is turned off.
+   */
+  discover: Object.freeze([...DEFAULT_DISCOVER]),
+})
+
+/**
+ * One reader per setting: takes the value from the file and returns the value
+ * to use, or calls `refuse` — which throws — with what the value must be and a
+ * hint. A value of the
+ * wrong type is refused rather than coerced: `"false"` is a truthy string, and
+ * reading it as "yes, ask me" or as "no, don't" would both be a guess about a
+ * safety preference.
+ */
+const READERS = {
+  confirmNewFiles(value, refuse) {
+    if (typeof value !== 'boolean') {
+      refuse('must be true or false', 'Example: { "confirmNewFiles": true }')
+    }
+
+    return value
+  },
+
+  discover(value, refuse) {
+    const example = `Example: { "discover": ${JSON.stringify(DEFAULT_DISCOVER)} }`
+
+    if (!Array.isArray(value)) {
+      refuse('must be a list', example)
+    }
+
+    const targets = value.map(entry => {
+      // `.agents/` and `.agents` are the same directory to anyone typing it.
+      const target = typeof entry === 'string' ? entry.replace(/\/+$/, '') : entry
+
+      // The same grammar every synced name passes, which also keeps `.git`,
+      // `node_modules`, `..` and absolute paths out of the sweep.
+      if (target !== ENV_FILES_TARGET && !isSafeRepoPath(target)) {
+        refuse(
+          `lists ${JSON.stringify(entry)}, which is not something envstash can discover`,
+          `Use "${ENV_FILES_TARGET}" for root dotenv files, or a directory inside the repo. ${example}`
+        )
+      }
+
+      return target
+    })
+
+    return [...new Set(targets)]
+  },
+}
+
+export function settingsPath() {
+  return join(configDir(), 'settings.json')
+}
+
+/**
+ * The settings, with defaults for whatever the file does not say — or for a
+ * file that is not there, which is the normal case.
+ */
+export function readSettings() {
+  const path = settingsPath()
+  const settings = { ...DEFAULT_SETTINGS, discover: [...DEFAULT_SETTINGS.discover] }
+
+  if (!existsSync(path)) {
+    return settings
+  }
+
+  let parsed
+
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    throw new CliError(`Could not read ${path} — it is not valid JSON.`, {
+      hint: 'Fix the file, or delete it to go back to the defaults.',
+    })
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new CliError(`${path} must hold a JSON object.`, {
+      hint: 'Example: { "confirmNewFiles": true }',
+    })
+  }
+
+  for (const [key, read] of Object.entries(READERS)) {
+    if (!(key in parsed)) {
+      continue
+    }
+
+    settings[key] = read(parsed[key], (must, hint) => {
+      throw new CliError(`"${key}" in ${path} ${must}.`, { hint })
+    })
+  }
+
+  return settings
+}