Cut startup cost, keep command arguments whole, tighten up conf and creds

[Korijn]

keycmd runs in front of every command a user puts through it, so its own import time is latency paid on each invocation. This moves the expensive imports off the startup path, fixes a quoting bug found while measuring, and cleans up two bits of duplication.

Verbose output is unchanged apart from one addition, verified by diffing a real end-to-end run against the pre-refactor code.

Startup time

import keycmd.cli goes from 94ms to 27ms above bare interpreter startup (keycmd --version end to end: 107ms → 40ms). Three imports cost more than the whole of the rest of the package, and none of them is needed on every run, so each moves into the function that needs it:

module	cost	now imported
keyring	~55ms (drags in urllib, ssl, email, importlib.metadata)	once there is a credential to look up
pprint	~8ms (mostly dataclasses)	under --verbose, through the new vlog_pretty
subprocess	~4ms	on the windows path only; the posix path replaces its own process and never spawns one

A caveat on that number, so it is not read as more than it is: a run that does look up a credential still pays for keyring, as it must, and lands within ~1ms of where it was. keyring transitively imports subprocess and dataclasses anyway, so for those runs the change relocates the cost rather than removing it. The full win lands on --version, --help, and a config without keys.

test_cli_import_stays_lean fails if one of the three wanders back up to module level.

argparse is the largest remaining import at ~9ms, and is left alone deliberately: the README documents its --help output verbatim, so hand rolling the parser would mean maintaining that text by hand and losing prefix abbreviation, for 9ms.

The dominant per-invocation cost is keyring's backend discovery

Worth recording, because it dwarfs everything above. keyring works out which backend to use by loading every backend registered by every installed package, on each invocation:

• default discovery: ~63ms
• PYTHON_KEYRING_BACKEND pinned: ~2ms

keycmd should not override a user's keyring configuration, so this is a README note rather than a code change — a new "Startup time" section under the existing keyring backends heading.

Related, --verbose now reports which backend keyring settled on. That decides where the credentials came from and was not reported anywhere, which makes it the first thing worth knowing when the credentials are not the ones expected.

Command arguments keep their word boundaries

Found while measuring, and fixed here. Every shell but cmd takes its command as one string after -c, and run_cmd built that string by joining the arguments with spaces. The shell then split it back into words, so whatever the first split had held together came apart:

# mytool received two arguments, not one
keycmd mytool --message 'hello world'

# and an apostrophe was a shell syntax error rather than an argument
keycmd python -c 'import sys; print(sys.argv[1:])' "it's"
# bash: -c: line 1: unexpected EOF while looking for matching `''

The two ways of invoking keycmd want opposite things here, and argv is what tells them apart:

• one argument is a command line already. keycmd 'echo $SECRET' is the form the README recommends and every example in it uses, and the shell is there precisely to interpret it, so it is handed over as typed. Variables, pipes and redirections keep working.
• several arguments are an argv vector. Each is quoted, so the shell reassembles exactly the words that were passed in.

Quoting is per dialect: shlex for posix shells, doubled quotes for powershell, which also reads a quoted command name as a string to print and so needs the call operator once its first word ends up quoted. cmd already kept its arguments separate after /C and is untouched.

This is a behavior change for the multi-argument form, in that shell syntax in an argument is no longer interpreted a second time: keycmd echo '$SECRET' now prints the name rather than the value. The single argument form the README documents is unaffected. Both forms are now spelled out under Usage. Two existing tests reached for the multi-argument form to check that the environment arrives and were relying on that second round of expansion; they now use the documented single argument form to test the same thing.

DRY and reorganization

• conf.py — load_conf walked the file system twice, once for .keycmd and once for pyproject.toml, over exactly the same ground. It now walks once, over a walk_up generator that replaces find_file along with its two @overloads and the first_only flag that made them necessary.
• creds.py — get_env spelled out the b64 and format handling, and the log line reporting it, once for keys and again for aliases, and carried both options through a five field KeyData tuple of which the alias path unpacked two as _, _. A key and an alias differ in where the credential comes from, not in what happens to it on the way into the environment, which is now what expose_conf says over a three field tuple.
• logs.py — vlog re-implemented log's prefix instead of calling it.

Subprocess layers: investigated, not changed

run_cmd builds [shell, "-c", "command line"], so a posix run is keycmd, replaced by the shell, replaced by the command. Skipping the shell when no argument carries shell syntax is feasible, but the layer measures at ~1.1ms, and it carries real hazards: shell builtins that shadow binaries with different flags (echo -e differs between bash's builtin and macOS /bin/echo), functions sourced from .zshenv, and on windows the cmd only builtins and .bat files. Not worth ~1ms against the ~67ms the import work already returns, so the shell stays.

Testing

ruff check, ruff format and ty check --error-on-warning all clean. The suite is 92 passed / 3 skipped with the keyring paths exercised (PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring), up from 68 / 14 on master.

New tests: the import guard; test_run_cmd_quoting, which asserts the command line built for bash, powershell and cmd alike, so the dialects that are not installed locally are covered the way the rest of the suite covers them; and test_run_cmd_preserves_argv, which runs a real command through every installed shell and checks the argv that arrives. The find_file tests become walk_up tests over the same three stopping conditions.

The README's example of verbose output had drifted from what keycmd actually prints (belonging to user rather than with user, and no format: field), and is refreshed to match.

🤖 Generated with Claude Code

https://claude.ai/code/session_016numkAkNoMbJRUgVWy63g7