Files
daedalus/INSTALL.md
T
nvaldez c210e17661 daedalus 0.3.0: argparse CLI + argcomplete shell completion, script-arg delegation
- cli.py rewritten on argparse (build_parser, REMAINDER pass-through: everything
  after the script name still belongs to the script); help/errors are
  argparse-rendered, exit code 2 kept for all daedalus errors
- completions.py (new): category-aware candidates for argcomplete - script names
  + unused labels narrowed by typed labels (daedalus test h<TAB> -> hello);
  --path completes scripts; after a completed script name daedalus offers
  nothing of its own and delegates .py scripts to their own parser via the
  run_python_script child with a rewritten COMP_LINE (daedalus hello -<TAB> ->
  hello's -h --help); SPEC 6.9 documents the autocomplete(parser) opt-in
- SPEC: item 1.5 reuse-first third-party policy, 3.8/3.10/3.11 argparse texts,
  3.13 completion catalog, 6.9 script opt-in, 9.6 argcomplete dependency
- argcomplete>=3.3 as runtime dep (guarded import: CLI runs without it);
  register-python-argcomplete line for ~/.bashrc; PYTHON_ARGCOMPLETE_OK marker
  in bin/daedalus; README/INSTALL/CHANGELOG updated; hello opts in
- tests: argparse CLI suites, completer units, end-to-end argcomplete probes
  through the bash fd-8 protocol and the delegation exec chain (autotest green,
  coverage 97%)

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-18 22:09:04 +01:00

6.9 KiB

Installing and using daedalus

Python 3.11 or newer. This checkout is an empty template (no scripts in SCRIPTS yet). Once you add scripts, the installed daedalus command bundles every registered one and works from any directory.

Back to the script list. Repository rules: SPEC.

Install

pipx installs daedalus into its own environment and puts the daedalus command on PATH.

Linux (Debian 12): paste once; open a new shell if pipx was just installed. Run the same block again to refresh from Git (main); do not use pipx upgrade daedalus for Git installs — it does not pull the repo.

daedalus_pipx_install() {
  r="${1:-git+ssh://git@example.com/your-org/daedalus.git@main}"
  command -v pipx >/dev/null || sudo apt install -y pipx
  pipx ensurepath 2>/dev/null || pipx ensurepath --force
  if pipx list --short 2>/dev/null | grep -qE '^daedalus '; then
    pipx install --force "$r"
  else
    pipx install "$r"
  fi
  daedalus --version
}; daedalus_pipx_install

No SSH key on the Git host: daedalus_pipx_install git+https://example.com/your-org/daedalus.git

Windows (PowerShell):

python -m pip install --user pipx
python -m pipx ensurepath  # once; then open a new terminal
pipx install git+ssh://git@example.com/your-org/daedalus.git

Without an SSH key for the Git host, use git+https://example.com/your-org/daedalus.git instead.

From a checkout

git clone git@example.com:your-org/daedalus.git
cd daedalus
pipx install .             # or, inside a virtual environment: pip install .

On Debian 12, pip install into the system Python is blocked (externally managed environment). Use pipx or a virtual environment.

Without installing

Linux: add to ~/.bashrc, call daedalus_checkout (clone once, then git pull --ff-only).

daedalus_checkout() {
  d="${1:-$HOME/daedalus}"
  [[ -d "$d/.git" ]] && git -C "$d" pull --ff-only \
    || git clone git@example.com:your-org/daedalus.git "$d"
  export PATH="$d/bin:$PATH"
}; daedalus_checkout

Windows: add <checkout>\bin to PATH (bin\daedalus.bat).

Check, upgrade, remove

daedalus --version        # confirm the install
daedalus_pipx_install      # reinstall from Git (same as first paste block)
pipx uninstall daedalus

Usage

daedalus --help                    # usage
daedalus [--list]                 # list the available scripts
daedalus <name> [args...]          # run a script; every argument after the name goes to it
daedalus <category> [category...]  # list scripts that have every category
daedalus <category> <name> [args...]  # run when the script has every category
daedalus --path <name>            # print where the script file is
daedalus --version                # print the installed version
  • daedalus NAME --help shows the help of the script, not of daedalus.
  • The exit code is the script's exit code. daedalus's own errors, such as an unknown name, exit with 2 and suggest close matches.
  • Listings print Daedalus Version:, a table of script, type, and categories, and the wrapped description under each row. Colors follow NO_COLOR / FORCE_COLOR and the terminal.

Environment variables:

Variable Effect
DAEDALUS_PYTHON Interpreter for .py scripts (default: the interpreter running daedalus)
DAEDALUS_BASH Override the bash used for .sh scripts
DAEDALUS_LOGLEVEL Console log level for Python scripts (default INFO)
DAEDALUS_NO_LOGGING Non-empty: Python scripts start without the daedalus logging setup
NO_COLOR / FORCE_COLOR Colors on listings and console logs

Python scripts run through daedalus/run_python_script.py: they get REPO_ROOT on PYTHONPATH (so import daedalus.<folder> works for shared code), file and console logging to ~/.daedalus/debug.log, and their sys.argv and exit code passed through unchanged.

Tab completion

Completion is built with argcomplete; it completes script names, category labels, and options — including script names after category labels.

Bash: register once per shell, e.g. in ~/.bashrc (the program on PATH must be able to import argcomplete):

eval "$(register-python-argcomplete daedalus)"

zsh:

autoload -U bashcompinit && bashcompinit
eval "$(register-python-argcomplete daedalus)"

Try it in a new shell:

daedalus hel<TAB>        # completes hello
daedalus test <TAB><TAB> # lists the scripts (and labels) for the prefix
daedalus --<TAB>         # completes the daedalus options

Notes:

  • register-python-argcomplete ships with the argcomplete package; it comes with the pipx/pip install (a daedalus dependency since 0.3.0) or with your system package (Debian: python3-argcomplete).
  • Arguments after the script name belong to the script: a Python script that calls argcomplete.autocomplete(parser) (SPEC item 6.9) completes its own arguments — daedalus hello -<TAB> offers hello's -h, --help. Otherwise the shell offers file names there.
  • A checkout run through bin/daedalus completes when the python3 it runs can import argcomplete and the marker comment stays in the launcher (SPEC item 3.13.7).

Add a script

  • Put the file in the folder for its type:
    Type Folder
    Python python/src/<name>/<name>.py
    bash bash/<name>.sh
    PowerShell powershell/<name>.ps1
    Batch batch/<name>.bat (CRLF line endings, Windows only)
  • Register it in SCRIPTS in daedalus/registry.py (set categories when it belongs to a group such as media or linux; the default is general).
  • Add a row to the Available scripts table in README.md. A test fails when a registered script is missing from that table.
  • Add tests under python/tests/ or bash/tests/. Python tests import the script with from daedalus.<name> import <name>; a new python/src/<folder>/ also needs a matching daedalus.<folder> entry in pyproject.toml (SPEC section 9).
  • Bump version in pyproject.toml, then run daedalus_pipx_install (or pipx install --force from the Git URL) so pipx picks up the change.
  • Run python autotest.py.

Details: SPEC section 6.

Development

python -m venv .venv
source .venv/bin/activate        # Windows: .\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
pip install -e .                 # daedalus command runs the checkout
python autotest.py               # every check; CI runs the same
python autotest.py pytest        # only some checks

autotest.py runs sanity (line endings, private keys, file size), Python syntax, pycodestyle, shellcheck, JSON, YAML, markdown lint, and pytest with coverage.