metal-kompanion/docs/configuration.md

Kompanion Configuration

Kompanion adheres to KDE’s KConfig conventions so deployments are kioskable and compatible with other desktop tooling.

Configuration File

• Location: ${XDG_CONFIG_HOME:-~/.config}/kompanionrc
• Group: [Database]
• Key: PgDsn=postgresql://user:pass@host/dbname

The CLI (kompanion) and MCP runner (kom_mcp) fall back to this entry when the PG_DSN environment variable is not set. If neither are present the in-memory DAL stub is used.

Initialization Wizard

• Run kompanion --init to launch an interactive wizard.
  • Autodetects reachable Postgres instances (tries postgresql://kompanion:komup@localhost/kompanion_test).
  • Inspects local socket (/var/run/postgresql) and existing databases owned by the current user via psql -At, offering them as defaults.
  • Prompts for host, port, database, user, password, or Unix socket path with sensible defaults.
  • Writes the resulting DSN to kompanionrc and exports PG_DSN for the current session.
  • If the target database is empty, it applies the SQL migrations shipped under share/kompanion/db/init/*.sql.
• The wizard is also triggered automatically the first time you run kompanion without a configured DSN.

CLI Modes

• Standard invocation: kompanion <tool> --request payload.json
• Interactive prompt: kompanion -I <tool> keeps a REPL open; enter JSON payloads or !prompt text to wrap plain text. Use -V/--verbose to echo request/response JSON streams.
• Use kompanion --list to enumerate available tools, including kom.meta.v1.project_snapshot for quick project context dumps.

Future HTTP Streaming

While current tooling focuses on stdio dispatch (for editor and agent integration), the roadmap includes an HTTP/2 or WebSocket streaming surface so MCP clients can maintain persistent conversations without leaving CLI compatibility behind. The same configuration keys will apply for both transports.

Test Database

Bootstrap a local Postgres instance using the provided scripts:

ROLE=kompanion PASS=komup db/scripts/create-test-db.sh kompanion_test

This loads the schemas from db/init/ and prepares the DSN you can reference in kompanionrc.