# 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. - [Install](#install) - [Usage](#usage) - [Tab completion](#tab-completion) - [Add a script](#add-a-script) - [Development](#development) Back to the [script list](./README.md#available-scripts). Repository rules: [SPEC](./SPEC.md). ## Install ### With pipx (recommended) [pipx](https://pipx.pypa.io/) 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. ```bash 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): ```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 ```bash 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`). ```bash 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 `\bin` to `PATH` (`bin\daedalus.bat`). ### Check, upgrade, remove ```bash daedalus --version # confirm the install daedalus_pipx_install # reinstall from Git (same as first paste block) pipx uninstall daedalus ``` ## Usage ```bash daedalus --help # usage daedalus [--list] # list the available scripts daedalus [args...] # run a script; every argument after the name goes to it daedalus [category...] # list scripts that have every category daedalus [args...] # run when the script has every category daedalus --path # 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.` 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](https://github.com/kislyuk/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`): ```bash eval "$(register-python-argcomplete daedalus)" ``` zsh: ```bash autoload -U bashcompinit && bashcompinit eval "$(register-python-argcomplete daedalus)" ``` Try it in a new shell: ```bash daedalus hel # completes hello daedalus test # lists the scripts (and labels) for the prefix daedalus -- # 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 -` offers hello's `-h`, `--help`. Otherwise the shell offers file names there. - Bash scripts share `bash/daedalus_common.sh` (SPEC item 6.10): the script sources it, defines `help()` and `main()`, and ends with `daedalus_bash_dispatch "$@"`. After the script name, TAB offers `--help`, `-h`, and `help`; running one of them prints the script's `help()`. - 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//.py` | | bash | `bash/.sh` | | PowerShell | `powershell/.ps1` | | Batch | `batch/.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](./README.md#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. import `; a new `python/src//` also needs a matching `daedalus.` 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](./SPEC.md#6-adding-a-script). ## Development ```bash 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.