Skip to content

windows-run-guide.md

Latest commit

 

History

History
238 lines (161 loc) · 5.08 KB

windows-run-guide.md

File metadata and controls

238 lines (161 loc) · 5.08 KB

Windows Run Guide

This guide is the Windows PowerShell path for installing and running KOMU CLI without guessing where the command lives.

1. Verify Python first

Run all of these in PowerShell:

Get-Command python
Get-Command py
Get-Command pip
where.exe python
where.exe py
where.exe pip

Healthy outcomes:

  • python resolves, or
  • py resolves, and
  • python -m pip works

If python or pip is not recognized, fix Python before debugging KOMU.

2. Check for the Microsoft Store alias issue

Windows can reserve python.exe and python3.exe as App Execution Aliases.

If python opens Microsoft Store or behaves inconsistently:

  1. open Settings
  2. go to Apps
  3. open Advanced app settings
  4. open App execution aliases
  5. disable python.exe and python3.exe

Then reopen PowerShell and run:

python --version
python -m pip --version

3. Use py if it is available

Some Windows users have py even when python is unreliable.

These are valid:

py --version
py -m pip --version
py -m venv .venv

If both python and py fail, repair or reinstall Python 3.11+ and enable the PATH option during setup.

4. Choose the right install mode

Option A: development install inside the repo

Use this when you are actively developing KOMU:

python -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
python -m pip install -e .[dev]
komu --help

Important:

  • komu lives in .venv\Scripts
  • it works while that venv is active
  • it is not a normal user-level install

Option B: user-level install on your machine

Use this when you want komu available outside the repo venv:

python -m pip install --user .

Then find the user Scripts directory:

$userBase = python -c "import site; print(site.USER_BASE)"
$userScripts = Join-Path $userBase "Scripts"
$userScripts

PowerShell must have $userScripts on PATH to discover komu.

Validation:

Get-Command komu
where.exe komu

If needed:

  1. add $userScripts to your user PATH
  2. close PowerShell
  3. open a new PowerShell session

Option C: end-user install with pipx

This is the cleanest install mode for a CLI product.

Install pipx once:

python -m pip install --user pipx
python -m pipx ensurepath

Restart PowerShell, then install KOMU:

pipx install .
komu --help

When the repo is published on GitHub:

pipx install git+https://github.com/<owner>/<repo>.git

5. Why komu only worked inside .venv

Because the command was created in .venv\Scripts, and PowerShell only knew about it when the venv activation script added that directory to PATH.

That behavior is correct for development mode.

It is not the same as:

  • python -m pip install --user .
  • pipx install .

Those installs create a command outside the repo venv.

6. Find where komu is installed

Use these commands:

Get-Command komu
where.exe komu
python -m pip show komu-cli

Typical locations:

  • repo venv: C:\path\to\repo\.venv\Scripts\komu.exe
  • user install: %APPDATA%\Python\PythonXY\Scripts\komu.exe
  • pipx install: the pipx-managed command path

7. Validate the install

Minimum checks:

komu --version
komu --help
komu providers list
komu profiles list
python -m komu_cli --help

If you want a fuller smoke pass:

komu profiles add --label dev --host 10.0.0.10 --username ubuntu --auth-method agent
komu profiles show dev
komu plan "restart nginx" --profile dev --no-inspect
komu explain last
komu history
komu profiles remove dev --yes

8. Shell restart rule

After any install that changes PATH or writes a new komu.exe into a Scripts directory, open a new PowerShell window before concluding the command is broken.

This matters for:

  • Python install or repair
  • pip install --user
  • pipx ensurepath
  • editing environment variables in Windows settings

9. Common command-not-found causes

python not recognized

  • Python missing
  • Python install directory missing from PATH
  • Microsoft Store alias interference

pip not recognized

  • Scripts directory missing from PATH
  • use python -m pip instead

komu not recognized

  • installed only inside a repo venv
  • user Scripts directory not on PATH
  • new shell not opened after install
  • pipx ensurepath not run yet

Activate.ps1 blocked

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

py not recognized

  • the Python launcher is not installed or not working correctly
  • use python if available, otherwise repair the Python install

10. Repo-specific details

  • the package entrypoint is defined in pyproject.toml as komu = "komu_cli.cli.app:run"
  • python -m komu_cli works through src/komu_cli/__main__.py
  • playbook data is shipped as package data
  • the package now includes py.typed for typed-distribution friendliness

For a deeper explanation of PATH and command routing, see: