Skip to content

installation.md

Latest commit

 

History

History
147 lines (102 loc) · 2.78 KB

installation.md

File metadata and controls

147 lines (102 loc) · 2.78 KB

Installation

KOMU CLI supports normal package installs, editable installs, and pipx installs. Because it is a CLI product, pipx is the recommended path for most end users.

KOMU also supports both:

  • local / self-hosted model workflows through ollama and openai-compatible
  • hosted API workflows through claude, openai, and gemini

Recommended: pipx

Windows

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

Restart PowerShell, then install from a local checkout:

pipx install .
komu --help

Future GitHub install:

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

Future PyPI install:

pipx install komu-cli

Linux / macOS

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install .
komu --help

Standard package install

Local source install

python -m pip install .
komu --help

User-level install on Windows

python -m pip install --user .

Then confirm PowerShell can find the installed command:

Get-Command komu
where.exe komu

If not, add your Python user Scripts directory to PATH and reopen the shell.

Editable install

For contributors:

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

On Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .[dev]

Validation

After any successful install:

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

Provider validation:

komu providers list
komu providers capabilities
komu providers health
komu providers check openai

Provider configuration

Use .env.example as the starting point for provider configuration.

Common local / self-hosted settings:

  • KOMU_OLLAMA_BASE_URL
  • KOMU_OLLAMA_MODEL
  • KOMU_OLLAMA_TRUST
  • KOMU_OPENAI_COMPAT_BASE_URL
  • KOMU_OPENAI_COMPAT_MODEL
  • KOMU_OPENAI_COMPAT_TRUST

Common hosted settings:

  • KOMU_CLAUDE_API_KEY
  • KOMU_OPENAI_API_KEY
  • KOMU_GEMINI_API_KEY

Preferred secret setup:

  • use real shell environment variables first
  • use .env only as a local convenience file
  • enable optional keyring support with KOMU_SECRET_BACKEND=keyring if you want secrets outside plaintext files

Avoid storing raw API keys in config.json.

Command-discovery notes

  • venv install: komu lives in .venv\Scripts or .venv/bin
  • user install: komu lives in the user Scripts/bin directory
  • pipx install: pipx exposes the command through its managed command path

For Windows-specific troubleshooting: