esysrepo-ctl 0.2.0

Control-plane tool for managing the native esysrepo CLI

esysrepo-ctl

Control-plane tool for installing, updating, diagnosing, and managing the native esysrepo CLI (distributed via Conan). Distributed as a Python package on PyPI.

Native repository operations use esysrepo / erepo (from the Conan package). This tool only manages the lifecycle of that native CLI.

Install

pipx install esysrepo-ctl

Or from a development checkout:

python -m pip install -e ".[dev]"

Both esysrepo-ctl and erepo-ctl are equivalent entry points.

Then install the native CLI (first run bootstraps a Python env + Conan 2 per ADR-0008):

# Interactive: detect mode, confirm, persist
esysrepo-ctl install

# Non-interactive installer-like (managed home venv + always-on wrappers)
esysrepo-ctl install --mode managed --yes

# Project-private: activate your venv first, then:
esysrepo-ctl install --mode project --yes

Mode	Conan lives in	Native esysrepo / erepo wrappers
project	Active project venv	That venv’s bin / Scripts (while activated)
pipx	Managed home venv	Managed …/esysrepo-ctl/bin
managed	Managed home venv	Managed …/esysrepo-ctl/bin

Overrides: ESYSREPO_CTL_MODE, ESYSREPO_CTL_YES=1, --reconfigure (ignore persisted mode). Choice is persisted under ESYSREPO_CTL_HOME / platform data dir (config.json).

Commands

Command	Purpose
install	Install the native esysrepo CLI via Conan
update	Update the native CLI (auto-bootstraps when allowed)
remove	Remove the native CLI from the Conan cache
doctor	Diagnose environment, PATH, and compatibility
version	Print control-plane and native CLI versions

esysrepo-ctl --help
esysrepo-ctl version
esysrepo-ctl doctor
esysrepo-ctl install
esysrepo-ctl install --mode managed --yes
esysrepo-ctl install --mode project --yes --reconfigure
esysrepo-ctl install --version 0.2.4
esysrepo-ctl --channel center install   # unnamed Conan Center-style refs
esysrepo-ctl update
esysrepo-ctl remove

Conan channel (ADR-0007)

By default, package refs use LibESys Artifactory identity:

esysrepo-cli/<version>@libesys/stable

Mode	How	Package ref shape
libesys (default)	--channel libesys or unset	…@libesys/stable
center	--channel center or ESYSREPO_CTL_CHANNEL=center	unnamed (esysrepo-cli/<ver>)

Configure the LibESys Conan remote yourself (or via CI vars CONAN_REMOTE_URL / CONAN_LOGIN_USERNAME / CONAN_PASSWORD). Install writes VirtualBuildEnv + VirtualRunEnv under the managed data dir and places wrappers per mode (above); doctor / discovery look at PATH, project Scripts/bin, and the managed bin.

Strict mode / no auto-bootstrap

By default, eligible commands (currently update) may auto-install the native CLI when it is missing (ADR-0005). Disable that with:

esysrepo-ctl --no-bootstrap update
# or
esysrepo-ctl --strict update

Auto-bootstrap is also disabled when any of these are set:

• CI=true (typical CI environments)
• ESYSREPO_CTL_NO_BOOTSTRAP=1
• ESYSREPO_CTL_STRICT=1

Explicit install / remove / doctor / version never trigger implicit install.

Exit codes

Stable codes for scripting (ADR-0006):

Code	Meaning
0	Success
1	General error
2	Usage error (bad arguments / unknown command)
3	Native esysrepo / erepo missing
4	Auto-bootstrap failure
5	Conan failure
6	Environment / compatibility error

Errors print to stderr as error: … with optional hint: … remediation lines.

Troubleshooting

Symptom	What to try
doctor reports Conan missing	Install Conan 2 and ensure conan is on PATH (or re-run esysrepo-ctl install --mode … --yes so ctl bootstraps Conan into the chosen venv)
doctor reports esysrepo missing	esysrepo-ctl install then re-check doctor / version
Install/update fails talking to remotes	conan remote list, fix auth/network, retry
Package installed but CLI not found	Check managed bin (esysrepo-ctl doctor) and Conan remotes
Wrong package identity / not found	Use default --channel libesys for Artifactory; ensure remote is configured
CI must not mutate the environment	Use --no-bootstrap or rely on CI=true
where esysrepo lists ~/.conan2/…/bin before the venv wrapper	Shell PATH is polluted (Conan cache bins first), so Windows never runs the .bat. cmd.exe: set "PATH=%VIRTUAL_ENV%\\Scripts;%PATH%" then where esysrepo — or call "%VIRTUAL_ENV%\\Scripts\\_esysrepo_ctl_fix_path.bat". PowerShell: $env:PATH = (@("$env:VIRTUAL_ENV\\Scripts") + ($env:PATH -split ';' | ? { $_ -notmatch '\\.conan2' })) -join ';'. Or deactivate/reactivate the venv after esysrepo-ctl install --mode project --yes.

esysrepo-ctl doctor
esysrepo-ctl version

Documentation

• Architecture overview
• CLI specification
• Quality requirements
• ADRs
• MVP implementation plan

Development

python scripts/setup-dev.sh   # or scripts/setup-dev.ps1 on Windows
pytest
pre-commit run --all-files