- new script python/src/init/init.py: locates the register-python-argcomplete that belongs to the running interpreter (venv bin, NOT the resolve()d symlink target - proven by a live pipx run), appends the managed hook block to ~/.bashrc between # BEGIN/END daedalus init markers, idempotent; --bashrc, --dry-run; Windows notice; zsh warning - per-script spec python/src/init/spec.md (SPEC 6.11/6.12), tests python/tests/test_init_script.py (13; the plain test_init.py name is taken by daedalus/tests) - registry entry, README row + section, pyproject packaging (daedalus.init), CHANGELOG 0.10.0, version pins Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
9.4 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 <alias> exists in the
config (move it into the managed markers or rename the alias).
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
- Clone or copy this template and name the Git remote for your team.
- Add a script under
python/src/,bash/,powershell/, orbatch/(see SPEC layout); bash scripts implement the sharedhelp()interface (SPEC item 6.10). - Register it in
daedalus/registry.py, add a row to the table above, write tests, bumpversioninpyproject.toml, and runpython 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.