pycontrol-install 0.1.0a2

uvx installer for the global pyControl GUI and its workspaces.

pycontrol-install

pycontrol-install is a small uvx installer for pyControl. It installs pycontrol-gui (and the pycontrol CLI) once per machine with uv tool install, scaffolds plain-data workspace folders, and remembers the workspace so the global pycontrol-gui command opens it on the next launch.

Install uv, then install pyControl and create a workspace:

uvx pycontrol-install my-workspace --launch

This:

1. runs uv tool install pycontrol-gui into a self-contained, uv-managed environment, putting pycontrol-gui and pycontrol on your PATH,
2. scaffolds the my-workspace data folder (no pyproject.toml, .venv, or lockfile — workspaces are pure data),
3. remembers it as the GUI's current workspace,
4. offers to create an OS shortcut (macOS ~/Applications, Windows Start menu, Linux application menu), and
5. launches the GUI (--launch).

After setup, launch the GUI from anywhere with pycontrol-gui.

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

uvx pycontrol-install . --launch

To install the app only, without creating any workspace, run it bare:

uvx pycontrol-install

This package intentionally uses uv. Users who prefer pip can still install and run pyControl manually from a Python 3.11+ virtual environment; see the pycontrol-core getting-started guide for the pip/venv workflow.

Usage

pycontrol-install [path] [--launch] [--force] [--shortcut | --no-shortcut] [--update-gui]

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 global install is refreshed (--reinstall) 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

Updating the GUI

uvx pycontrol-install --update-gui

Reinstalls the newest pycontrol-gui against a freshly refreshed package index, preserving integration extras recorded in the uv tool receipt. (uv tool upgrade pycontrol-gui also works; --update-gui additionally guarantees the index is revalidated and the pyControl resolution strategy is applied.)

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:

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

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