Skip to content

Install

El Hidratador is a single Python package with no runtime dependencies. Every install path below produces the same hidratador command.

Requirements

Requirement Version Needed for Required
Python 3.11 or newer the package and the CLI yes
sqlite3 3.35 or newer the ledger yes, bundled with CPython
git any cloning a repository for staging no
gh any observing a repository, publishing reconciled comments no
docker any creating a staging sandbox no

The last three are adapters. hidratador doctor reports a missing one as a warning, not a failure. The core needs none of them.

python3 --version
python3 -c "import sqlite3; print(sqlite3.sqlite_version)"

Path 1 — install from PyPI

python3 -m pip install el-hidratador

This installs the hidratador console script into the environment's bin directory. Use a virtual environment if the system Python is managed by your operating system:

python3 -m venv ~/.venvs/hidratador
source ~/.venvs/hidratador/bin/activate
python3 -m pip install el-hidratador

Path 2 — install from a checkout

Clone the repository and install it in editable mode. The dev extra brings in the toolchain the checks need: ruff, mypy, pytest, and coverage.

git clone https://github.com/hamanakam1/el-hidratador.git
cd el-hidratador
python3 -m pip install -e ".[dev]"

The docs extra is separate, and installs mkdocs and mkdocs-material for building this site:

python3 -m pip install -e ".[dev,docs]"

Path 3 — the container image

The repository ships a Dockerfile that builds the package into a python:3.12-slim image. The image runs as an unprivileged user, and the ledger lives on a volume rather than inside the image.

make docker-build

Or build it directly:

docker build -t el-hidratador:local .

Run it:

make docker-run

docker run --rm el-hidratador:local --help

The ledger is at /var/lib/hidratador/ledger.sqlite inside the container, and that path is a declared volume. Mount your own to keep state between runs:

docker run --rm \
  -v "$HOME/.el-hidratador:/var/lib/hidratador" \
  el-hidratador:local status

The container image is Linux only.

Path 4 — the devcontainer

The repository ships a devcontainer, so there is nothing to install by hand. Open the project in your editor and choose "Reopen in Container", or from the command line:

devcontainer open .

The container image carries Python 3.13, the gh CLI, ShellCheck, and the project dependencies:

.devcontainer/devcontainer.json

{
  "name": "El Hidratador",
  "image": "mcr.microsoft.com/devcontainers/python:1-3.13-bookworm",
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {},
    "ghcr.io/shellcheck/stable:1": {}
  },
  "postCreateCommand": "python3 -m pip install --upgrade pip && python3 -m pip install -e \".[dev]\" && python3 -m pip install yamllint && make help"
}

Open it with "Reopen in Container", then run the checks inside the container:

make check

The ledger lives in the container's home directory by default. To keep it on your host instead, mount a directory and point $HIDRATADOR_DB at it:

{
  "mounts": [
    "source=${localWorkspaceFolder}/.hidratador,target=/home/vscode/.el-hidratador,type=bind"
  ],
  "containerEnv": {
    "HIDRATADOR_DB": "/home/vscode/.el-hidratador/ledger.sqlite"
  }
}

Path 5 — run from source

No install at all. From the repository root, the module entry point works directly:

python3 -m el_hidratador --help
python3 -m el_hidratador demo --text

This is the form to use while you are working on the package. It is equivalent to the hidratador script in every other respect, including exit codes and JSON output.

Verify the install

Four checks, in order.

# 1. The console script is on PATH and reports its version
hidratador --version

hidratador 0.1.0

# 2. The ledger can be created and read back
hidratador --db /tmp/hidratador-check.sqlite init
hidratador --db /tmp/hidratador-check.sqlite status | jq '.tasks_by_status'

{}

# 3. The environment is ready
hidratador doctor | jq '{healthy, failed, warnings}'

{
  "failed": [],
  "healthy": true,
  "warnings": []
}

A fresh machine reports ledger and journal-mode as warnings until hidratador init has run against the default path, because there is no file to inspect yet. Both are warnings, not failures: the exit code is still 0.

# 4. A full lifecycle runs end to end, against a scratch ledger
hidratador demo --text

El Hidratador demonstration
================================

Created the ticket M-1001 in status INBOX.
  Scope keys: repo/api, repo/edge
  A scope key is a resource, not a description. Two tickets that share a scope key cannot run at the same time.

Clean up the check file:

rm -f /tmp/hidratador-check.sqlite /tmp/hidratador-check.sqlite-wal /tmp/hidratador-check.sqlite-shm

Environment variables

Two, and only two. Neither holds a credential.

Variable Default Purpose
HIDRATADOR_DB ~/.el-hidratador/ledger.sqlite The ledger path. Used only when --db is absent.
HIDRATADOR_GITHUB_DB ~/.el-hidratador/github.sqlite The GitHub adapter's observation and outbox database.

Resolution order for the ledger is --db PATH, then $HIDRATADOR_DB, then the default. Both variables expand ~.

export HIDRATADOR_DB="$HOME/.el-hidratador/ledger.sqlite"
export HIDRATADOR_GITHUB_DB="$HOME/.el-hidratador/github.sqlite"

There is no configuration file, no config file search path, and no other environment variable. Everything else is a flag. See the example configuration for a deployment shape you can turn into real flags.

Uninstall

python3 -m pip uninstall el-hidratador

Removing the package does not remove the ledger. To delete the state as well:

rm -rf "$HOME/.el-hidratador"

If you installed from a checkout in editable mode, remove the checkout too:

rm -rf /path/to/el-hidratador

Check that nothing is left on PATH:

command -v hidratador || echo "hidratador is gone"