KOMU CLI

AI-powered SSH operations assistant

Natural-language server operations with transparent plans, playbook-first workflows, provider routing, and review before execution.

Important

KOMU is built around one hard rule: natural language is not permission to hide commands.
Plans stay visible. Risk stays annotated. Review stays in front of execution.

Note

KOMU CLI is already installable and usable as a serious beta-stage tool.
Packaging is ready for public distribution, but PyPI publication is not live yet.

What KOMU is

KOMU CLI is a product-grade command-line tool for operators, platform engineers, and developers who want AI assistance for server operations without turning infrastructure work into blind automation.

It helps you move from natural-language intent to a reviewed operational plan:

• identify the task
• match a verified playbook where possible
• route through a suitable provider when AI reasoning is needed
• show the plan, commands, risk, and approval boundary
• execute through SSH only after explicit review

That product philosophy is the point: AI should assist operators, not obscure operations.

Why this exists

There is no shortage of ways to generate shell commands. That is not the hard part.

The hard part is building an operations assistant that remains:

• inspectable
• risk-aware
• reviewable
• extensible
• usable from a real CLI

KOMU exists because "natural language for servers" is not enough if the system hides what it plans to do, bypasses review, or treats risky infrastructure changes like casual chat output.

Feature surface

Area	What KOMU does today
Natural-language task flow	Turn requests like install docker or restart nginx into structured, inspectable plans
SSH-first workflow	Work through server profiles, connection tests, environment inspection, and remote execution scaffolding
Playbook-driven execution	Prefer verified playbooks before falling back to provider-generated planning
Plan + approval flow	Show plan source, steps, commands, risk, root visibility, and approval requirements before execution
Diagnostics and repair	Support diagnose/fix flows, failure summaries, and repair-plan preparation
Explainability	Explain why a playbook or provider was selected and what the plan is trying to change
History and sessions	Persist task history, session records, execution summaries, and audit-friendly traces
Provider routing	Support manual choice, automatic routing, capability-aware selection, and controlled fallback
Provider health checks	Check provider reachability and model availability without crashing unrelated flows
Local + hosted model strategy	Work with local/self-hosted and hosted API providers through a shared provider layer
Security-oriented review	Classify risk, highlight destructive commands, and keep dangerous actions visible
Clean architecture	Keep CLI UX, orchestration, providers, playbooks, SSH, storage, and security separated cleanly

What using KOMU looks like

$ komu
$ komu providers list
$ komu providers health
$ komu profiles add --label prod-web --host 10.0.0.20 --username ubuntu --auth-method agent
$ komu inspect --profile prod-web
$ komu plan "set up nginx reverse proxy" --profile prod-web
$ komu explain last
$ komu history
$ komu sessions

Interactive shell

KOMU opens into an interactive shell by default. Inside that shell, treat it like a real product shell, not a place to repeat the outer command name.

$ komu
komu[no-profile | opencode | manual] > providers list
komu[no-profile | opencode | manual] > profiles add --label web --host 10.0.0.20 --username ubuntu --auth-method agent
komu[web | opencode | manual] > inspect
komu[web | opencode | manual] > install docker
komu[web | opencode | manual] > history
komu[web | opencode | manual] > exit

Shell behavior is now split clearly:

• shell and CLI commands such as profiles list, providers health, config show, history, and explain last run directly
• natural-language requests such as install docker or diagnose nginx route into planning and review
• if you accidentally type komu providers list while already inside the shell, KOMU normalizes or redirects that input instead of treating it as a task
• no-profile mode still allows local and informational commands; only planning, inspection, and execution paths require a usable target profile

Useful shell commands:

• help
• profiles list
• profiles add
• providers list
• providers current
• history
• sessions
• exit

Provider system

The provider layer is now one of KOMU's strongest architectural pieces.

KOMU supports a hybrid provider strategy:

• use hosted APIs when you want stronger remote inference or have a weaker local machine
• use local or self-hosted providers when control, privacy, or data locality matters more
• use OpenAI-compatible endpoints when you already operate your own gateway or inference service

Provider routing is not a hardcoded gimmick. KOMU can now evaluate:

• provider capabilities
• provider trust level: trusted, restricted, or untrusted
• deployment scope: local, remote, or hybrid
• current config completeness
• cached health-check state
• recent provider failures
• task wording and use case
• explicit user provider choice

Hosted / API providers

Provider	Fit	Current direction
OpenAI / ChatGPT API	strong general hosted reasoning	direct hosted API path
Claude	long-context hosted reasoning	direct hosted API path
Google Gemini API	hosted general-purpose reasoning	direct hosted API path
OpenCode	general planning	remote / stub-friendly
DeepSeek	diagnostics and repair reasoning	remote / stub-friendly
Kimi	long-context workflow planning	remote / stub-friendly
GLM-5	fast drafting and fallback	remote / stub-friendly

Local / self-hosted providers

Provider	Fit	Current direction
Ollama	local model workflows, privacy-sensitive setups, offline-ish operation	local HTTP provider
OpenAI-compatible endpoint	self-hosted inference, private gateways, local or remote custom endpoints	hybrid HTTP provider

Provider features now in place

• shared provider contract
• capability matrix
• health checks
• trust-aware provider sandboxing
• provider readiness states
• request context minimization and redaction
• structured response validation
• suitability scoring
• local vs remote awareness
• manual provider selection
• automatic routing
• fallback when a provider is unavailable or fails

Useful provider commands:

$ komu providers list
$ komu providers capabilities
$ komu providers health
$ komu providers check ollama
$ komu providers check openai-compatible
$ komu providers use deepseek
$ komu providers current

For deeper provider configuration and routing details, see docs/providers.md.

Weak vs strong systems

KOMU is designed to support both light local setups and stronger self-hosted environments. The right provider strategy depends on the machine you are actually using.

Environment	Recommended direction	Why
Weaker laptop or workstation	prefer hosted providers such as OpenAI, Claude, Gemini, or other hosted backends	stronger inference without local model overhead
Strong local machine or GPU-equipped host	prefer Ollama or a self-hosted OpenAI-compatible endpoint	better control, privacy, and local routing options
Private infra / internal platform	prefer self-hosted endpoints and local providers where possible	cleaner data locality and private deployment paths
Mixed setup	keep a stable default provider and enable auto routing after health checks pass	lets KOMU use local or hosted options based on task suitability

Local models are useful, but they are not a magic replacement for stronger hosted APIs. KOMU supports both approaches because different operators have different constraints.

For custom endpoints, KOMU is intentionally cautious by default:

• local Ollama and local gateways are typically treated as restricted
• remote OpenAI-compatible endpoints default to a lower-trust posture unless trust is explicitly raised
• lower-trust providers stay inside the same plan, risk, and approval path as every other provider

Command showcase

Goal	Command
Launch the interactive shell	komu
Open shell explicitly	komu shell
Inspect providers	komu providers list
Run provider health checks	komu providers health
Inspect provider capabilities	komu providers capabilities
Add a target profile	komu profiles add --label web --host 10.0.0.20 --username ubuntu --auth-method agent
Switch active profile	komu profiles use web
Inspect a target	komu inspect --profile web
Ask for an operation	komu ask "install docker" --profile web
Generate a reviewed plan	komu plan "set up nginx reverse proxy" --profile web
Review the last explanation	komu explain last
Inspect task history	komu history
Inspect session history	komu sessions

Installation

Install paths at a glance

Audience	Recommended path	Result
CLI users	pipx install .	isolated CLI install with komu on PATH
Source users	python -m pip install .	normal package install
Contributors	python -m pip install -e .[dev]	editable development workflow
Future public users	pipx install komu-cli or pip install komu-cli	intended once PyPI publishing is live

Why pipx is the cleanest option

KOMU is a CLI-first product. pipx is usually the best install path because it:

• isolates dependencies cleanly
• exposes the komu command directly
• avoids tying normal usage to a project-local .venv
• feels closer to how end users will consume the tool later

Windows

Install pipx:

py -m pip install --user pipx
py -m pipx ensurepath

Open a new PowerShell window after ensurepath, then install from the repository:

pipx install .
komu --help
Get-Command komu

Linux / macOS

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

Standard install from source

python -m pip install .
komu --help

Editable install for development

Windows PowerShell

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

Linux / macOS

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

Windows command discovery notes

If PowerShell still does not recognize komu, the usual reasons are:

• the tool was installed only inside a local .venv
• the Python user Scripts directory is not on PATH
• pipx ensurepath has not been run yet
• the shell has not been restarted after installation

Use these docs if Windows command routing is confusing:

• path_route.md
• docs/windows-run-guide.md
• docs/run-and-install.md

Provider configuration

Use .env.example as the starting point.

Common local / self-hosted configuration:

• KOMU_OLLAMA_BASE_URL
• KOMU_OLLAMA_MODEL
• KOMU_OPENAI_COMPAT_BASE_URL
• KOMU_OPENAI_COMPAT_MODEL
• KOMU_OPENAI_COMPAT_TRUST

Common hosted provider configuration:

• KOMU_CLAUDE_API_KEY
• KOMU_OPENAI_API_KEY
• KOMU_GEMINI_API_KEY

Secret handling guidance:

• prefer real shell environment variables first
• use .env only as a local convenience file, not as secure secret storage
• optional keyring resolution can be enabled with KOMU_SECRET_BACKEND=keyring
• do not store raw API keys in config.json

Quick start

Go from install to a reviewed plan quickly:

1. Install KOMU.
2. Verify the CLI entrypoint with komu --help.
3. Inspect providers with komu providers list.
4. Check provider health with komu providers health.
5. Create a target profile.
6. Inspect the target host context.
7. Generate a plan.
8. Review before execution.

Example:

komu --help
komu providers list
komu providers health
komu profiles add --label web --host 10.0.0.20 --username ubuntu --auth-method agent
komu inspect --profile web
komu plan "restart nginx and verify service state" --profile web --no-inspect
komu explain last

Safety and trust

Tip

KOMU is deliberately trying to feel like a controlled operations assistant, not a blind auto-executing shell bot.

Note

Provider sandboxing in KOMU is application-layer trust hardening, not container isolation.
Providers help with reasoning, but they still stay inside plan validation, risk review, and operator approval.

Before execution, KOMU can make the following visible:

• exact plan steps
• exact commands
• risk level
• destructive-command warnings
• root privilege visibility
• approval requirements
• provider or playbook selection reason
• expected change summary
• rollback guidance where available

Trust-building layers already present:

• playbook-first planning
• reusable risk engine
• typed review panels
• explicit approval for higher-risk operations
• explainability for plan and provider choice
• history, session, and audit logging
• provider health checks for local and hosted endpoints
• provider trust levels and restricted-provider behavior
• provider readiness states: ready, restricted, needs-configuration, unavailable
• context minimization before provider calls
• structured provider output validation
• no provider-to-execution bypass
• credential validation before provider use
• env-var-first provider secret handling
• plaintext secret-storage warnings for local config
• secret redaction in provider errors and logs

Provider safety model

KOMU does not treat every provider as equally trustworthy.

• official hosted APIs can be configured as higher-trust reasoning backends
• local Ollama and self-hosted gateways are useful, but they still stay inside the same review flow
• custom OpenAI-compatible endpoints are treated more cautiously by default, especially when they are remote
• lower-trust or partially configured providers can be marked restricted or unavailable instead of silently participating

Provider influence is bounded:

• the provider receives minimized context, not raw config dumps or secret material
• malformed provider output is rejected instead of flowing directly into execution
• generated commands still pass through plan modeling, risk analysis, and approval checks
• provider choice, safety posture, and failure reasons remain inspectable through provider status and explainability flows

Credential hygiene

KOMU now validates provider setup earlier and more explicitly.

• missing credentials are surfaced before use
• placeholder or malformed values are flagged
• endpoint configuration problems are separated from reachability failures
• model availability issues are distinguished from auth failures where practical
• validation messages are written to stay actionable without leaking raw secret values

Secret handling

Preferred order:

1. environment variables
2. optional keyring-backed lookup
3. local .env only as a convenience layer

Discouraged:

• raw provider keys in config.json
• copying API tokens into prompts
• treating local config storage as a secret manager

For deeper review:

• SECURITY_CHECKLIST.md
• docs/security.md
• docs/explainability.md
• docs/audit-logging.md

Architecture

KOMU is structured so the CLI presentation layer is not the business logic.

flowchart LR
    CLI["CLI + Shell UX"] --> Core["Core Orchestration"]
    Core --> Playbooks["Playbooks + Planning"]
    Core --> Providers["Provider Adapters + Routing"]
    Core --> SSH["SSH Execution + Inspection"]
    Core --> Security["Risk Engine + Review"]
    Core --> State["Profiles + Config + Storage"]
    Core --> History["History + Sessions + Audit Logs"]

Loading

Key layers:

• cli/ for Typer commands, interactive shell flow, and Rich presentation
• core/ for bootstrap and shared application wiring
• services/ for provider routing, planning, execution, explainability, history, and profiles
• providers/ for adapters, live HTTP handling, health checks, and suitability logic
• playbooks/ for verified operational flows
• ssh/ for connection, execution, inspection, and remote command capture
• security/ for command risk analysis and approval modeling
• storage/ and logging/ for structured persistence, task history, sessions, and auditability

For the deeper architecture view, see docs/architecture.md.

Current maturity

Note

KOMU CLI is now a serious beta-stage foundation. The product is installable, the CLI flows are real, the provider system is meaningfully expanded, and the review model is in place. It should still be treated as an operator-reviewed tool rather than a production-proven autonomous system.

What is already in place:

• installable CLI with console entrypoint
• interactive shell
• SSH-oriented profile workflow
• playbook-driven planning path
• provider routing, trust levels, health checks, and capability matrix
• explainability, task history, and session history
• structured execution review and audit-friendly traces

What is still best treated as beta:

• wider live-host validation across real infrastructure
• broader real-world API validation across every provider/backend combination
• deeper enterprise policy packs and team workflows
• future multi-server fan-out execution

Troubleshooting

komu is not recognized

Check:

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

Most common causes:

• KOMU was installed only inside .venv
• the user Scripts directory is not on PATH
• the shell was not reopened after install
• pipx ensurepath was not run yet

Windows Python confusion

If python opens Microsoft Store or behaves unexpectedly:

• check Windows App Execution Aliases
• try py if the Python launcher is installed
• confirm the Python install path and Scripts path are visible to PowerShell

Use:

• docs/windows-run-guide.md
• path_route.md

PowerShell blocks Activate.ps1

Use a process-scoped bypass:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Provider credentials are missing

Check:

komu providers list
komu providers current
komu providers check openai

Then configure the relevant API key or endpoint settings in your environment or .env.

KOMU now distinguishes between:

• missing or placeholder credentials
• invalid endpoint configuration
• unreachable endpoint
• authentication rejection
• model availability problems
• malformed provider responses

Ollama or a local endpoint is not reachable

Check:

komu providers health
komu providers check ollama
komu providers check openai-compatible

Most common causes:

• Ollama is not running
• the configured base URL is wrong
• the requested model is not installed
• the endpoint is OpenAI-like, but not fully OpenAI-compatible
• the endpoint is working, but its trust level remains restricted or untrusted by design

Documentation

Core docs:

• Installation
• Run and Install
• Windows Run Guide
• Development
• Distribution
• Architecture

Operational docs:

• Providers
• Profiles
• Playbooks
• Execution Flow
• History
• Security
• Explainability
• Audit Logging
• Testing
• Extensibility
• Roadmap

Repo notes:

• Path Routing
• Security Checklist
• Scan Report
• Provider Expansion Report

Development

git clone <repo-url>
cd komu-cli
py -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
py -m pip install -e .[dev]
komu --help
py -m compileall src
py -m unittest discover -s tests -p "test_*.py"

Contributor workflow details live in:

• docs/development.md
• CONTRIBUTING.md

License

MIT. See LICENSE.