Files
daedalus/README.md
T
nvaldez cdc209536f feat: daedalus init - register argcomplete tab completion (v0.10.0)
- 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>
2026-11-19 09:31:05 +01:00

207 lines
9.4 KiB
Markdown

# daedalus (template)
Starter repository for daedalus:
one CLI, many small scripts, each with tests.
```bash
daedalus <name> [args...] # run a script
daedalus <category> [category...] # list scripts in the categories (AND)
daedalus --list # list everything
```
**[Install, usage, and development](./INSTALL.md)** ·
[SPEC](./SPEC.md) (how the repo is maintained) ·
[CHANGELOG](./CHANGELOG.md)
## 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:
```bash
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.
```bash
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.
```bash
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.
```bash
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.
```bash
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.
```bash
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](./INSTALL.md#tab-completion).
### 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.
```bash
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](./SPEC.md#2-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.