From d39e1e4d896f012f8b2a25c2f03d3db1a006b1f2 Mon Sep 17 00:00:00 2001 From: Anthony Ettinger Date: Thu, 13 Aug 2026 15:38:54 +0000 Subject: [PATCH] Add worked examples to secrets and secrets ssh help MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commander's usage line shows only the first alias, so `logicsrc secrets` — the spelling people actually type — was invisible in its own help. The examples carry it, alongside the flows worth copying: link/up/down, the ssh backup round trip, and a plan → dry-run → approve sync. Co-Authored-By: Claude Opus 5 (1M context) --- packages/cli/src/index.ts | 50 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 405109b..92d9eb3 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -416,7 +416,34 @@ const credentials = program // `secrets` is what people reach for; keep it pointing at the same group // rather than growing a second, divergent surface. .alias("secrets") - .description("Credential Sharing OpenSpec: portable, auditable secret sync."); + .description("Credential Sharing OpenSpec: portable, auditable secret sync.") + // Commander's usage line only ever shows the first alias, so the everyday + // spelling — `logicsrc secrets` — is only discoverable from the examples. + .addHelpText( + "after", + ` +Examples: + # .env in this directory, shared with the team + logicsrc secrets teams link link this directory to a team project/env + logicsrc secrets up push .env to the linked environment + logicsrc secrets down pull it back down + logicsrc secrets down staging pull another env of the same project + + # ~/.ssh keys and config, backed up under your username + logicsrc secrets ssh push profullstack back up ~/.ssh to vault ssh-- + logicsrc secrets ssh pull profullstack restore it on another machine + logicsrc secrets ssh agent profullstack load the keys into ssh-agent, not onto disk + + # anywhere to anywhere, one plan at a time + logicsrc secrets inspect --provider env --path .env + logicsrc secrets plan --from env --from-path .env --to railway \\ + --to-project --to-config + logicsrc secrets sync --plan dry run — no writes + logicsrc secrets sync --plan --approve + +Every command also answers to "credentials" and "creds". Full guide: docs/credential-sharing.md +` + ); function endpointFromOptions(options: Record, prefix: "" | "from" | "to"): CredentialEndpoint { const pick = (name: string) => { @@ -494,7 +521,26 @@ credentials const secretsSsh = credentials .command("ssh") - .description("Back up ~/.ssh keys and config to an end-to-end-encrypted vault, keyed by username."); + .description("Back up ~/.ssh keys and config to an end-to-end-encrypted vault, keyed by username.") + .addHelpText( + "after", + ` +Examples: + logicsrc secrets ssh push profullstack back up ~/.ssh to vault ssh-- + logicsrc secrets ssh push --dry-run show what would go up, write nothing + logicsrc secrets ssh push --include authorized_keys + logicsrc secrets ssh list profullstack what the vault holds: paths, kinds, modes + logicsrc secrets ssh pull profullstack restore onto this machine, permissions and all + logicsrc secrets ssh pull --force also overwrite local files that differ + logicsrc secrets ssh agent profullstack --lifetime 3600 + logicsrc secrets ssh pull profullstack anthony when this box logs in as someone else + +The vault is ssh--, so "teams vaults" lists it as project ssh, env +. Key pairs, config, config.d/* and allowed_signers travel; known_hosts +and authorized_keys need --include. Nothing that would overwrite a file which +already differs is written without --force. +` + ); const collect = (value: string, previous: string[]): string[] => [...previous, value];