pycontrol-install

pycontrol-install manages the lifecycle of a global pyControl app. It installs pycontrol-gui and the pycontrol CLI with uv tool install, switches between published and editable local sources, updates and uninstalls the app, scaffolds plain-data workspaces, and manages the OS launcher.

Complete lifecycle

1. Install the manager

Install uv, then install pycontrol-install as a uv tool:

uv tool install --prerelease if-necessary-or-explicit pycontrol-install

For development of the manager itself, install its checkout as editable instead:

ROOT="/Users/lustiga/HHMI Dropbox/Andy Lustig/Code/karpova_lab/pyControl/rewrite"
uv tool install --editable "$ROOT/pycontrol-install"

Edits under pycontrol-install/src/ are then immediately live.

2. Install and launch pyControl

Install the published core and GUI, create a workspace, remember it, optionally create an OS launcher, and launch:

pycontrol-install my-workspace --launch

The workspace is pure data: it has no virtual environment, lockfile, or launcher script. After setup, launch the remembered workspace from the OS launcher or from any terminal:

pycontrol-gui

To initialize the current directory as the workspace, pass . explicitly:

pycontrol-install . --launch

To install the app without creating a workspace:

pycontrol-install

3. Switch to editable local core and GUI sources

Point the global app at sibling pycontrol-core/ and pycontrol-gui/ checkouts:

pycontrol-install --use-local "$ROOT"
pycontrol-gui

The global commands and OS launcher stay the same. Python source edits in both checkouts are immediately live; no reinstall is needed. Ordinary pycontrol-install workspace operations preserve this local mode.

--update-gui intentionally stops in local mode because replacing editable sources during an update would be surprising. Use Git to update the checkouts, or explicitly switch back to PyPI.

4. Switch back to published packages

pycontrol-install --use-pypi

This replaces both editable checkouts with the newest published core and GUI, while preserving installed optional extras.

5. Update published pyControl

pycontrol-install --update-gui

This refreshes the package index and reinstalls the newest published packages, preserving optional extras. It refuses to replace a local editable install; run --use-pypi first. uv tool upgrade pycontrol-gui is also available for published installs.

To update the separately installed manager:

uv tool upgrade pycontrol-install

An editable manager checkout does not need upgrading because its source edits are already live.

6. Uninstall

Remove the pyControl app, OS launcher, and all GUI QSettings:

pycontrol-install --uninstall

This removes the pycontrol-gui uv tool environment, including the injected core CLI. It deliberately leaves pycontrol-install available for a future reinstall. Remove the manager too when it is no longer wanted:

uv tool uninstall pycontrol-install

Usage

pycontrol-install [path] [--launch] [--force] [--shortcut | --no-shortcut]
pycontrol-install {--update-gui | --use-local ROOT | --use-pypi | --uninstall}

Without path, only the app is installed — no workspace is created or touched. Pass a path (. for the current directory) to also scaffold and remember a workspace; relative paths are resolved from the directory where the command is run. Re-running pycontrol-install is safe: the current PyPI or local source mode is preserved and workspace scaffolding is a safe merge.

Examples:

pycontrol-install                         # install/refresh the app only
pycontrol-install my-workspace --launch
pycontrol-install ~/pycontrol-workspaces/ws1 --with-slack
pycontrol-install my-workspace --no-shortcut

Integration helpers

Optional integration dependencies are installed into the global tool environment:

pycontrol-install my-workspace --with-slack
pycontrol-install my-workspace --with-notion
pycontrol-install my-workspace --with-s3
pycontrol-install my-workspace --with-integrations

To add an integration to an existing install without touching any workspace, combine it with --update-gui:

pycontrol-install --update-gui --with-slack

Analysis helpers

Install pandas dataframe support into the global app environment with:

pycontrol-install --with-analysis

This is separate from --with-integrations, which installs only the Slack, Notion, and S3 helpers. Re-running the installer or using --update-gui preserves the analysis extra recorded in the uv tool receipt.

Release smoke tests

Package indexes can be overridden:

pycontrol-install test-workspace \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/

Development

uv sync --group dev
uv run pytest
uv run ruff check src tests