pycontrol-init

pycontrol-init 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-init 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 instead:

uvx pycontrol-init . --launch

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-init [path] [--launch] [--force] [--shortcut | --no-shortcut] [--update-gui]

path defaults to the current directory. Relative paths are resolved from the directory where the command is run. Re-running pycontrol-init is safe: the global install is refreshed (--reinstall) and workspace scaffolding is a safe merge.

Examples:

pycontrol-init
pycontrol-init my-workspace --launch
pycontrol-init ~/pycontrol-workspaces/ws1 --with-slack
pycontrol-init my-workspace --no-shortcut

Updating the GUI

uvx pycontrol-init --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-init my-workspace --with-slack
pycontrol-init my-workspace --with-notion
pycontrol-init my-workspace --with-s3
pycontrol-init my-workspace --with-integrations

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

uvx pycontrol-init --update-gui --with-slack

Release smoke tests

Package indexes can be overridden:

pycontrol-init 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