PyPI renders the README alone; ./INSTALL.md, ./SPEC.md and ./CHANGELOG.md have nothing to resolve against. Links now point at the public Gitea repository (anchors kept). 0.13.0's page is immutable and keeps its broken links; the project page shows the newest release's README. Found by the owner on the 0.13.0 page. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
11 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 |
publish |
Python | release | Release daedalus to PyPI: guarded chained build (clean tree, exact v<version> tag, PyPI-free version, tooling), twine check, --upload (credentials stay with twine) |
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).
publish
publish releases the package itself. Guards first — clean working
tree, HEAD exactly tagged v<version> (the version from
pyproject.toml), the version not yet on PyPI, and build + twine
available in the running interpreter — then a chained build
(the sdist must rebuild the wheel, SPEC item 9.2.1) and
twine check. Without --upload it stops there and prints the
artifacts; with --upload it uploads exactly this version's sdist
and wheel. Credentials never touch the script: twine prompts or
reads ~/.pypirc (username __token__, your PyPI API token).
daedalus publish # build + check, print next step
daedalus publish --upload # ... and upload to PyPI
Exit codes: 2 not run from a checkout, 3 dirty tree, 4 not
exactly tagged v<version>, 5 build/twine missing, 6 version
already on PyPI (or PyPI unreachable), 7 build failed, 8 twine
check failed, 9 upload failed.
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.