Files
daedalus/README.md
T
nvaldez 41c8b99bd6 feat: gpgtools ssh-config-summary - per-host table of gpg-enabled logins (v0.11.0)
- read-only: one row per marker-managed block in ~/.ssh/config (or
  --config PATH): alias, hostname, user, key id (first 8 chars of
  the identity's SHA256 fingerprint via ssh-keygen -lf, material
  digest as fallback), and the fallback identity's name
- no managed blocks / missing config: fact + configure_ssh hint,
  exit 0 always (read-only command)
- spec items 2.8 + section 13 first, then tests, then code (SPEC
  6.12); 10 new tests (100 in test_gpgtools.py), registry
  description, README section, CHANGELOG 0.11.0, version pins

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 09:49:35 +01:00

9.9 KiB

daedalus (template)

Starter repository for daedalus: one CLI, many small scripts, each with tests.

daedalus <name> [args...]        # run a script
daedalus <category> [category...]  # list scripts in the categories (AND)
daedalus --list                  # list everything

Install, usage, and development · SPEC (how the repo is maintained) · CHANGELOG

Available scripts

Script Type Categories What it does
gpgtools Python gpg YubiKey GPG/SSH helpers: initialize (gnupg readiness check + install), initialize_yubikey (fresh machine, steps 1-4), send_pubkey (resolve key, verify possession, append to a server), store_publickey (install the key from the machine being granted access), configure_ssh (marker-managed per-host ssh block)
hello Python test Prints a hello line and the daedalus version
hello_bash Bash test Sample bash script through the shared help() interface
init Python setup Enable tab completion for daedalus: register argcomplete in bash (appends the managed hook block to ~/.bashrc), idempotent

Run the sample script:

daedalus hello          # hello from daedalus 0.4.0
daedalus hello_bash me  # hello, me (from daedalus bash)
daedalus hello_bash -h  # usage from hello_bash's help()
daedalus test hello     # same, through the category prefix
daedalus test           # list the scripts in the 'test' category

daedalus --list prints the version, a script / type / categories table, and each description wrapped under each row.

gpgtools

initialize checks that gnupg is ready on this machine and installs what is missing — the gnupg-only half of initialize_yubikey, with no card expectations. Its use is on-site: on a bare server where you are about to run store_publickey --fingerprint, this is the command that makes the gpg-dependent sources work.

daedalus gpgtools initialize             # check gnupg, install when missing
daedalus gpgtools initialize --dry-run   # already ready, or the install command
Argument Default Meaning
--dry-run off Print what would happen (already ready or the install command); change nothing

Exit codes: 0 gnupg ready (installed or already present), 2 package install failed or gpg still unusable after it, 3 gpg missing and no known package manager.

initialize_yubikey runs the fresh-machine flow for YubiKey-backed GPG and SSH (steps 1-4 of the wiki guide): install gnupg when missing, check the card, fetch the public key from the card's URL field, and write the gpg-agent SSH config. Steps 5-7 are per-server and covered by the subcommands below.

daedalus gpgtools                         # overview of the subcommands
daedalus gpgtools initialize_yubikey      # prepare this machine
daedalus gpgtools initialize_yubikey --dry-run   # print the plan only
Argument Default Meaning
--dry-run off Print the plan, write nothing
--gnupg-home DIR GNUPGHOME or ~/.gnupg Which GnuPG home to configure

Exit codes: 0 ready, 2 package install failed, 3 gpg missing and no known package manager, 4 no card found, 5 public-key fetch did not pair the keyring, 6 keyring unpaired and the card carries no URL.

send_pubkey covers guide steps 5-6 for one server: resolve the SSH public key from one of five sources, prove possession of the private half with a challenge signature (the YubiKey itself signs; PIN prompts go to the user), then append the line to the target's authorized_keys — idempotent, fingerprint-checked against stores, and nothing is sent when verification fails.

daedalus gpgtools send_pubkey --yubikey you@server
daedalus gpgtools send_pubkey --fingerprint <FP> you@server
daedalus gpgtools send_pubkey --url https://keys.openpgp.org/vks/v1/by-fingerprint/<FP> you@server
daedalus gpgtools send_pubkey --pubkey "ssh-ed25519 AAAA... comment" you@server
daedalus gpgtools send_pubkey --file /media/usb/yubikey_auth.pub you@server
daedalus gpgtools send_pubkey --yubikey --dry-run you@server   # resolve only
Argument Default Meaning
--yubikey — Key from the plugged YubiKey via gpg-agent (must be the only agent key)
--url URL — Armored OpenPGP public key at a URL ([A] subkey is exported)
--fingerprint FP — Searched: local keyring → keys.openpgp.org → keyserver.ubuntu.com
--pubkey LINE — The literal SSH public key line
--file PATH — File holding the key line, e.g. a .pub from a USB stick (no network, no gpg)
--no-verify verification on Skip the proof-of-possession signature (explicit risk acceptance)
--dry-run off Resolve and print the key; verify and send nothing

Additional exit codes: 7 ssh to the target failed, 8 no source resolved a key, 10 proof-of-possession verification failed (nothing was sent).

store_publickey is the mirror for the on-site bootstrap: run it on the machine that access is being granted to — a server with ssh password authentication disabled that no key authorizes yet, where you are logged in at the console. It resolves the same five sources and appends the key into this machine's authorized_keys, so the machine holding the YubiKey can ssh in afterwards. There is no proof-of-possession (the private half is, by design, elsewhere); instead both resolve-and-store subcommands print an identity block — line, source, and the key material's SHA-256 — to compare across machines. Existing entries are preserved, nothing is duplicated, and directory/file modes are forced to 700/600.

daedalus gpgtools store_publickey --file /media/usb/yubikey_auth.pub
daedalus gpgtools store_publickey --fingerprint <FP>
daedalus gpgtools store_publickey --pubkey "ssh-ed25519 AAAA... comment"
daedalus gpgtools store_publickey --file /media/usb/yubikey_auth.pub --dry-run  # print only
Argument Default Meaning
sources — Same five sources as send_pubkey (exactly one required)
--authorized-keys FILE ~/.ssh/authorized_keys Where to install the key
--dry-run off Resolve and print the key; write nothing

Additional exit codes: 8 no source resolved a key.

configure_ssh covers guide step 7 for one host: it writes a marker-managed Host <alias> block into the ssh client config. Outside the markers your config is preserved byte-for-byte; re-runs replace the block (idempotent), and an unmanaged Host with the same alias is refused rather than shadowed. It never connects anywhere.

daedalus gpgtools configure_ssh --alias vault1 --hostname 203.0.113.10 --user admin
daedalus gpgtools configure_ssh --alias vault1 --dry-run   # print only
daedalus gpgtools configure_ssh --alias vault1 --no-fallback  # YubiKey only
Argument Default Meaning
--alias NAME required The ssh Host alias to configure
--hostname HOST the alias HostName value
--user USER ssh's default User value
--pubkey FILE ~/.ssh/yubikey_auth.pub Primary IdentityFile (must exist)
--fallback FILE ~/.ssh/id_ed25519 Fallback IdentityFile, included only when it exists
--no-fallback off Never add a fallback IdentityFile
--config PATH ~/.ssh/config Which ssh client config to edit

Additional exit code: 11 an unmanaged Host with the same alias exists in the config (move it into the managed markers or rename the alias).

ssh-config-summary prints what is enabled where, read-only: one row per managed block — alias, hostname, user, the key id (first 8 chars of the identity's SHA256 fingerprint, material-digest fallback), and the fallback identity. Same id on two rows means the same gpg key guards both hosts.

daedalus gpgtools ssh-config-summary
daedalus gpgtools ssh-config-summary --config FILE
Argument Default Meaning
--config FILE ~/.ssh/config Which ssh client config to read

Shell completion

Bash (and other shells argcomplete supports) completes script names and category labels: daedalus hel + TAB completes hello, daedalus test h + TAB completes hello inside the category, and options complete after -. Run daedalus init once to register the hook in ~/.bashrc (below); see also INSTALL.

init

init is the one-time shell-side setup: it finds the register-python-argcomplete that belongs to this exact daedalus interpreter (so a pipx install wires its own venv, not some other python), appends the hook to ~/.bashrc between managed markers, and tells you how to activate it now. Installing daedalus never touches your shell — this command does. It is idempotent: re-running on an already registered ~/.bashrc writes nothing.

daedalus init                 # register completion in ~/.bashrc
daedalus init --dry-run       # print the block and the target, change nothing
daedalus init --bashrc FILE   # a different bashrc
Argument Default Meaning
--bashrc FILE ~/.bashrc Target file for the managed hook block
--dry-run off Print the block and the target, change nothing

Exit code: 3 when register-python-argcomplete is nowhere to be found (reinstall daedalus — argcomplete is a declared dependency).

Getting started

  1. Clone or copy this template and name the Git remote for your team.
  2. Add a script under python/src/, bash/, powershell/, or batch/ (see SPEC layout); bash scripts implement the shared help() interface (SPEC item 6.10).
  3. Register it in daedalus/registry.py, add a row to the table above, write tests, bump version in pyproject.toml, and run python autotest.py.

hello is the sample script: copy its file, registry entry, README row, and tests to add your own. Unknown names exit with code 2 and suggest close matches.