Skip to content

path_route.md

Latest commit

 

History

History
197 lines (130 loc) · 3.92 KB

path_route.md

File metadata and controls

197 lines (130 loc) · 3.92 KB

KOMU Command Routing and PATH Behavior

This document mirrors path_route_md in a Markdown-renderable form for GitHub and local editors.

1. Why komu only worked inside .venv

During a development install such as:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Python creates the CLI launcher here:

.\.venv\Scripts\komu.exe

When the virtual environment is activated, PowerShell temporarily prepends:

.\.venv\Scripts

to PATH for the current shell session.

That is why:

  • komu works while the venv is active
  • komu stops being discoverable when the shell is no longer using that venv

This behavior is normal for a development install. It does not mean the CLI entrypoint is broken.

2. Where the komu command is created after installation

The exact location depends on the installation mode.

Development venv install

Command location:

<repo>\.venv\Scripts\komu.exe

User-level install with python -m pip install --user .

Command location:

<USER_BASE>\Scripts\komu.exe

Discover it with:

python -c "import site; print(site.USER_BASE)"

pipx install

pipx creates an isolated environment for KOMU and exposes the CLI through the command path managed by pipx ensurepath.

3. How PowerShell discovers commands

PowerShell resolves a command name like komu from:

  1. aliases
  2. functions
  3. cmdlets
  4. scripts and executables found on PATH

For a Python CLI like KOMU, the important part is PATH:

  • komu.exe must exist
  • the directory containing komu.exe must be on PATH

Validation:

Get-Command komu
where.exe komu

4. Which PATH entries matter

For a venv install:

<repo>\.venv\Scripts

For a user install:

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

For pipx:

  • the path added by python -m pipx ensurepath

5. How editable installs behave

Editable install:

python -m pip install -e .

It installs launcher scripts into the current environment and points imports back to the source tree.

That means:

  • editable install inside .venv is venv-local
  • editable install with --user is user-level

6. How end users should install the tool

Recommended:

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

When the repo is published:

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

Alternative single-machine user install:

python -m pip install --user .

Then ensure the user Scripts directory is on PATH.

7. Windows troubleshooting

If komu is not recognized:

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

If python is not recognized:

  • check PATH
  • check App Execution Aliases
  • check the Windows Python launcher

If Activate.ps1 is blocked:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

8. What changed in the repo

  • pyproject.toml now carries stronger distribution metadata
  • the console script entrypoint remains komu = "komu_cli.cli.app:run"
  • src/komu_cli/__main__.py supports python -m komu_cli
  • src/komu_cli/py.typed is now shipped
  • packaging metadata tests were added
  • install docs now separate venv, user, and pipx install modes

9. Practical validation commands

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

10. Core takeaway

There are three correct ways to route the command:

  1. .venv\Scripts\komu.exe for development
  2. user Scripts komu.exe for --user installs
  3. pipx-managed command exposure for end users

KOMU now supports all three. The remaining step on any machine is making sure PowerShell can see the correct Scripts directory for the chosen install mode.