# 0043 - CLI arguments: every option before the command, `--exec -- [args...]` Status: in flight on branch `cli-args` (agent `cli-args`), landed by the lead as one cycle after review. Facts: `~/.tmp/cli-args/FACTS.md` (the long form; the short form is below). ## Goal Owner decision 1 (2026-11-19, plan 0040 decision 49), looking at the README's `socialweb-computer run request --name vm1 --exec id -- --atproto-oauth-qr`: "why is the --atproto-oauth-qr flag behind exec and the double hyphen? that doesn't seem like how CLIs that exec other things usually work, usually it would be `socialweb-computer run request --name vm1 --atproto-oauth-qr --exec -- some-command --with-that-commands-args`". ## Facts - Parsing: `main.go` parses a verb's own options (`internal/clicfg/options.json`, the names in `builtVerbs`) and hands the rest on; `splitWords` cuts it at `--`; the tail is parsed by `compose.ParseAppArgs` against the verb's application in `deploy/apps/option-map.yaml` (`market-requester`, `market-bidder`, `ssh-gateway`) into the root object: the identity and sign-in options (`--atproto-oauth-qr`, `--atproto-oauth`, `--atproto-handle`, `--atproto-identity-mode`, `--atproto-pds-url`, `--expect-handle`, `--skip-qr`, `--associate-with`), network, ingress, comms, bidder DIDs, contract (`--vm-name`, `--allow-bidder-dids`, `--user-data`, `--policy`) and the `options` passthrough. - Why: `run request`, `run bidder` and `run gateway ssh` are the Go ports (2026-10-12/13) of the TypeScript programs `request-vm-ssh`, `hono-bidder` and `hono-socialweb-computer-ssh`. The CLI used to exec them with everything after `--`; the port kept that argv as the tail and mapped every old flag in `option-map.yaml`. There is no embedded program any more, so the `--` separates nothing. - Verbs with that tail: `run request`, `run requester`, `install requester` (market-requester), `run bidder` (market-bidder), `run gateway ssh` (ssh-gateway). Installed units (`run bidder --handle %i --fg`, `run requester --name %i --fg`) pass no tail. `internal ns-exec` and `internal deno-fence` already take a command after `--`. - Ten names were defined in both tables for `run request`: `exec`, `hold`, `skip-ssh`, `secrets`, `tunnel`, `agent`, `guest-tools`, `associate`, `association-ref`, `state-dir`. - `--exec` took one string; `ssh root@guest ` hands it to root's login shell on the guest (`bash -c`): a shell line, never an exact argv. stdin is the ssh's stdin; a non-zero remote exit makes the verb exit 1; `run request ssh` and `run requester ssh` share the code. - Consumers outside this repo pin no CLI binary. The requester repo's guest user-data (`modules/user-data/src/lib.rs`) passes own options only and keeps working. The atlibs app page (`atlibs-socialweb-computer-app/index.html:130`) shows the old tail as a snippet. - Correction (review, 2026-11-19): kcp's guest requester script (`internal/atproto/cloudinit/agent.go` `guestRequesterRunScript`) is NOT own-options-only: it appends `-- --plc-directory-url

--ingress-proxy-host ` whenever `/etc/socialweb-guest-agent/r2-network.env` names them, which the requester writes when its network's PLC is not plc.directory (`internal/market/requester/secrets.go` `guestNetworkOf`: staging and local market networks; never prod). The script is the requester's (user_data), the `socialweb-computer` it runs is the bidder's own executable (`internal/guestseed/binaries.go`), so the two can be of different releases. - The prod hosts (read 2026-11-19, read only): the four bidders (hat-7, 8, 9, 10) run `run bidder --handle bobvmbuilder.bsky.social --fg` from the `install bidder` template, with no tail and no ExecStart drop-in (hat-7 holds an inactive `socialweb-computer-bidder@johnandersen777.bsky.social.service.d/10-oauth-qr.conf.bak` with a `-- --atproto-identity-mode pdsAccount ...` tail: systemd reads only `*.conf`, and that instance does not run); their config.json has no `bidder-options` and no `bidder-spec-file`. The gateway host's hand-written `/etc/systemd/system/swc-ssh-gateway.service` runs `run gateway ssh --host-backend proc --fg --name ssh-gateway --instance sg --state-dir /var/lib/socialweb-computer/socialweb/sg --network-timeout 10m -- --ssh-public-listen 0.0.0.0:22 --ssh-web-listen 127.0.0.1:8789 --public-origin https://ssh.socialweb.computer --ssh-operator-did did:plc:5svqtrhheairglgiiyvutzik --ssh-max-accounts 64`, and `scripts/promote.sh` restarts it on every promote: the new binary refuses that line (exit 2), so it must move to a spec file before the promote (decision 12). - Conventions: `kubectl exec pod [opts] -- cmd args`, `sudo [opts] -- cmd args`, `env [opts] -- cmd args`, `docker run [opts] image cmd args`: the tool's options first, `--` ends them, the command's argv is passed exactly. Plain `ssh host cmd args` joins words for the remote shell, the trap this plan avoids. ## Decisions 1. The layout: `socialweb-computer [options] [--exec -- [args...]]`. Every option of the verb, its own (options.json) and its application's (option-map.yaml), comes before `--`, in any order. 2. `--exec` is a flag (no value). The command is every word after `--`, passed to the guest as that exact argv. The old forms are removed, not a second mode. They fail with an error that names the new form: `--exec id` and `--exec=id` ("--exec takes no value: --exec -- id"), `--exec` with no `--`, `--exec --` with no command, `--` without `--exec`, and options after `--` ("-- ends the options: put --atproto-oauth-qr before --exec --"). Without `--exec` the behaviour is the same as before: an interactive session when stdin is a terminal, otherwise "no session opened". 3. Argv-safe exec: each word is single-quoted (POSIX: `'` written as `'\''`) and the words are joined into the one line that ssh hands to the guest's login shell, which unquotes it back to the same argv. No word is split, globbed or expanded. To use a shell, write `--exec -- sh -c '...'`. stdin, the exit status rule and the `--hold` reconnect stay as they were. 4. The same rule for every verb that execs: `run request`, `run request resume`, `run request ssh `, `run requester ssh --contract `, and so `--hold` followed by a later `ssh -- cmd`. 5. `--` means only "end of options; the rest is the command". A verb that takes no command refuses anything after it. 6. Two tables, each name defined once per verb: options.json holds the CLI's own options, option-map.yaml an application's. A verb names its application in `builtVerbs`; the parser takes both kinds on one command line. A name defined in both for one verb is an error of the tables that the CLI reports before it parses anything. The duplicates are removed from option-map.yaml (the options.json ones read the same values). `--help` lists the application's options. 7. `run requester`, `install requester`, `run bidder` and `run gateway ssh` get the same treatment: the same parser and the same reason (no embedded program). `dev up`, `install bidder|gateway` and `upgrade` take no tail: nothing to change. 8. Migration: every caller in this repo changes in the same change (Go, the test host, testkit and system tests, modules, scripts, docs, site). Records of past runs (ARCHITECTURE findings and measurements, plan logs, research, `0040-findings.md`) stay as they ran. Statements of current behaviour are updated. 9. The test host: a module's `args` are the CLI's new form (`--exec -- true`). The host moves `--exec -- ...` to the end of the command line it builds. Its own `exec` line inputs (request.ssh, request.put, logs) run as `--exec -- bash -c `, which is what root's login shell did with them before. A new `argv` input passes an exact argv. The compat binary (0006:compat, the previous rc) gets the old layout while its `run request --help` lacks the new usage line. Step 7 removes that once the previous rc carries this change. 10. Composition coverage: `--exec` already runs in 0003 (run, ssh2), 0006 (run, compat), 0017, the staging stand-up (`--exec -- true`) and every request.ssh/request.put user (0005, 0013, 0015, ...). 0003's ssh2 now runs `sh -c 'uname -a; id; printf "%s|" "$@"' x 'a b' -c "d'e"` and also asserts `a b|-c|d'e|`. Its `Linux` and `uid=` checks stay. 11. The guest requester script across releases. The script now asks the guest's binary: when `run request --help` prints `--exec -- [args...]` (`cloudinit.RequestExecUsage`, the same text the CLI's usage line and the test host's probe use) it puts the PLC and ingress options with the others, else after `--`. Without a PLC or ingress there is no tail in any release, so prod is never affected. The four cases (`~/.tmp/cli-args/r2matrix.py`: each release's script run against each release's binary, v0.0.0 = 688c2105 as the old side): | script (requester) \ binary (bidder) | old (v0.0.0) | new | | --- | --- | --- | | old | parses | refused (exit 2) on a non-public PLC; parses on prod | | new | parses (probe: old form) | parses (probe: new form) | The old-requester/new-bidder case on a staging or local network has no fix this side of a second parsing mode in the new binary (the old script is fixed in the requester's user_data): it needs a requester older than its network's bidders and a fromGuest guest with guest tools, which neither gate runs (staging runs one build; 0006:compat starts no guest requester) and prod cannot produce. By the owner's no-backcompat rule it is not built; the lead or the owner may decide otherwise (the only form that closes it: the new binary accepting `-- --plc-directory-url

--ingress-proxy-host ` after `--guest-requester`). 12. Hand-written units take nothing a later or an earlier binary may refuse. An option that only some releases take on the command line goes in the spec file both releases read (`readSpec` is the same in v0.0.0 and this branch): the ssh gateway's `--ssh-gateway-spec-file` (`ssh {publicListen, webListen, operatorDid, maxAccounts}`, `options [{name: public-origin}]`), a bidder's `--bidder-spec-file` (`identity: {mode: oauthQr}` is what `--atproto-oauth-qr` set). CONTRIBUTING's oauthQr recipe now writes the spec file. 13. `internal parse-args ...` (hidden) parses a command line as that subcommand would, runs nothing, and prints `{verb, words, app, command}`; `scripts/check-cli-args.sh` (in `deploy/check.sh --fast`) builds the CLI and runs `--help` of every verb of `verbApps` (read from `main.go`; fewer than five read fails) and of the four command verbs, each of which must show `--exec -- [args...]` (a name defined in both tables fails it); parses every unit template's ExecStart and fails when it parsed none; and fails on an old form in tracked text: an option after `--` in a unit, a drop-in or a cloud-init text, `--exec` with a value in `tests/`, `scripts/`, `rust/`, `infra/` and `deploy/` (the second review found `tests/vmm/tests/vmm.rs:282` this way), and ` -- --