You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
refactor(cli): unify CLI args + env-var bindings across every subcommand
Define a single `GlobalArgs` clap struct and `#[command(flatten)]` it into
every subcommand's args. Every flag now has a matching `SOCKET_*` env var
binding (precedence: CLI > env > default). Legacy `SOCKET_PATCH_PROXY_URL`,
`SOCKET_PATCH_DEBUG`, `SOCKET_PATCH_TELEMETRY_DISABLED` are still honored at
runtime via a one-shot deprecation warning that fires even under `--silent` /
`--json`.
Behavior changes:
- `--offline` now means strict airgap on every command (was three different
things across apply / repair / rollback). On `repair`, `--offline` and
`--download-only` are mutually exclusive.
- `repair --download-mode` default flipped from `file` to `diff` to match
every other command. Users who need the legacy per-file blob behavior
opt in with `--download-mode file`.
- `apply` and `repair` gain `--api-url` / `--api-token` / `--org` for free
via the flatten (previously only readable via env).
- `--debug` and `--no-telemetry` promoted from env-only toggles to CLI flags.
CLI_CONTRACT.md rewritten around a single global-args table plus a small
per-subcommand section for local flags. New tests: `cli_global_args.rs`
(compose test: every global flag × every subcommand) and
`cli_env_deprecation.rs` (legacy-env warning fires under `--silent` /
`--json`).
Assisted-by: Claude Code:opus-4-7
@@ -19,129 +19,98 @@ This document defines the **public surface** of the `socket-patch` binary. Anyth
19
19
20
20
**Bare-UUID fallback.**`socket-patch <UUID>` is rewritten to `socket-patch get <UUID>`. The UUID shape checked is the standard 8-4-4-4-12 hex pattern (case-insensitive). See [`src/lib.rs::looks_like_uuid`](src/lib.rs).
21
21
22
-
## Flags — long and short forms
23
-
24
-
Every flag below is part of the contract. The default values are pinned by parser tests.
Same as `apply` plus: `--one-off` (bool), `--org` (string), `--api-url` (string), `--api-token` (string). Positional `identifier` is **optional** (omit to rollback everything).
The hidden alias `--no-apply` on `--save-only` is **part of the contract** — it does not appear in `--help` but is widely used in existing scripts.
70
-
71
-
### `scan`
72
-
73
-
| Long | Short | Default | Type |
22
+
## Global arguments
23
+
24
+
In v3.0 every subcommand accepts the same set of "global" flags via a single shared `GlobalArgs` struct that's `#[command(flatten)]`-ed into each per-command struct (`crates/socket-patch-cli/src/args.rs`). Subcommands that don't actually consume a given flag accept it silently — e.g. `list --global` parses fine and is a no-op. Every flag also has an environment-variable binding; precedence is **CLI arg > env var > default**.
25
+
26
+
| Long | Short | Env var | Default | Type | Semantic |
27
+
|---|---|---|---|---|---|
28
+
|`--cwd`| — |`SOCKET_CWD`|`.`| path | Working directory |
29
+
|`--manifest-path`|`-m`|`SOCKET_MANIFEST_PATH`|`.socket/manifest.json`| path | Manifest location (resolved relative to `--cwd`) |
30
+
|`--api-url`| — |`SOCKET_API_URL`|`https://api.socket.dev`| string | Authenticated API endpoint |
31
+
|`--api-token`| — |`SOCKET_API_TOKEN`| (none) | string | Auth token (absence selects the public proxy) |
The `--offline` semantics unified in v3.0. Previously `apply` enforced strict airgap, `repair` skipped network ops, and `rollback` failed when blobs were missing. All three now mean the same thing: never contact the network, fail loudly when a required local source is missing. On `repair`, `--offline` and `--download-only` are mutually exclusive.
48
+
49
+
## Per-subcommand arguments
50
+
51
+
Beyond the globals above, each subcommand defines a small set of local arguments.
|`repair`|`--download-only`|`SOCKET_DOWNLOAD_ONLY`| Repair-specific cleanup mode (mutually exclusive with `--offline`) |
62
+
|`setup`| (none beyond globals) | — | — |
90
63
91
-
`--apply` opts JSON callers into the full discover → select → apply pipeline. Without it, `scan --json` stays read-only (discovery + `updates` array only). No effect outside `--json` mode — the non-JSON path always prompts the user interactively. Designed for unattended workflows (cron jobs, bots that open PRs).
64
+
`scan --apply` opts JSON callers into the full discover → select → apply pipeline. Without it, `scan --json` stays read-only (discovery + `updates` array only). No effect outside `--json` mode — the non-JSON path always prompts the user interactively.
92
65
93
-
`--prune` opts into garbage collection. When set, `scan` removes manifest entries for packages no longer present in the crawl, then deletes orphan blob, diff, and package-archive files from `.socket/`. Off by default (v3.0) so a temporary uninstall doesn't silently destroy manifest state. Pair with `--apply` (or use `--sync`) for the auto-update workflow.
66
+
`scan --prune` opts into garbage collection. When set, `scan` removes manifest entries for packages no longer present in the crawl, then deletes orphan blob, diff, and package-archive files from `.socket/`. Off by default (v3.0) so a temporary uninstall doesn't silently destroy manifest state.
94
67
95
-
`--sync` is sugar for `--apply --prune` — the canonical single-flag bot invocation. `scan --json --sync --yes` discovers, applies, and reconciles state in one pass.
68
+
`scan --sync` is sugar for `--apply --prune` — the canonical single-flag bot invocation. `scan --json --sync --yes` discovers, applies, and reconciles state in one pass.
96
69
97
-
`--dry-run`(`-d`) previews what `--apply` / `--prune` / `--sync`would do without mutating disk. In JSON mode, `apply.patches[*]`is populated with would-be actions (computed via `decide_patch_action` against the current manifest) and `gc.prunable*` / `gc.orphan*` fields report counts via the cleanup helpers' built-in dry-run mode. No effect without at least one of `--apply`, `--prune`, or `--sync`.
70
+
`--dry-run` previews what `apply` / `rollback` / `scan --apply` / `repair`would do without mutating disk. In JSON mode, the envelope is populated with would-be actions and counts.
98
71
99
-
### `list`
72
+
The hidden alias `--no-apply` on `get --save-only` is **part of the contract** — it does not appear in `--help` but is widely used in existing scripts.
All v3.0 env vars use the `SOCKET_*` prefix. Three legacy `SOCKET_PATCH_*` names are still honored at runtime for compatibility: on first read of any of the three the binary emits a one-shot deprecation warning to stderr (the warning fires unconditionally — even under `--silent` / `--json` — because it's a transition signal users need to see). The legacy names will be removed in the next major release.
`repair` (alias `gc`) is a first-class command for cleaning up the `.socket/` directory without running a scan. For the combined discover-and-apply workflow with GC, use `scan --sync --json --yes`; for cleanup alone, use `repair` (or `gc`) directly. The `gc` visible alias is part of the contract — removing or demoting it is a MAJOR bump.
**Note:**`repair`'s `--download-mode` default differs from every other command (`file` vs `diff`). This is intentional — repair restores legacy per-file blobs needed to apply any patch.
0 commit comments