klynx-cli 0.0.3

Klynx Textual CLI application package.

Klynx CLI (klynx-cli)

klynx-cli is the official command-line and TUI interface for Klynx. It provides:

• An interactive terminal UI (klynx)
• A headless automation mode (klynx run ...)
• Session persistence, model switching, auth helpers, diagnostics, and shell completion

The package installs two equivalent commands:

• klynx
• klynx-cli

Install (PyPI)

pip install -U klynx-cli

Optional browser tooling (needed only for browser-based tools):

playwright install chromium

Quick Start (5 Minutes)

1) Configure your model API key

klynx auth login --model gpt-4o

Or set environment variables manually (example):

export OPENAI_API_KEY="sk-..."

2) Launch the interactive TUI

klynx

3) Run one task immediately

klynx "review the current repository and propose a refactor plan"

4) Run in headless mode

klynx run "fix the failing tests and explain the root cause"

5) Resume the latest session

klynx resume --last

Usage Tutorial

Tutorial A: Interactive coding workflow in TUI

1. Start TUI: klynx
2. Enter a task, for example:
   • implement retry logic for the API client and add tests
3. Use slash commands inside TUI:
   • /help
   • /context
   • /compact
   • /model
4. Continue follow-up prompts in the same session to iterate.

Tutorial B: CI-friendly headless execution

Use run for scripted workflows:

klynx run --json "summarize current test failures"
klynx run --show-tools "apply fixes and run verification"
klynx run --mode plan --approval on-request "design and implement a migration path"

Tutorial C: Work across multiple directories

Allow additional directories when needed:

klynx run --add-dir ../shared-lib --add-dir ../docs "check cross-repo compatibility"

Tutorial D: Manage session history

klynx session list
klynx session show --last
klynx session compact --last
klynx session delete <session_id>

Common Commands

klynx run "..."
klynx resume --last
klynx session list
klynx auth status
klynx auth login --model gpt-4o
klynx models list
klynx models set gpt-4o --scope global
klynx config show
klynx doctor
klynx completion powershell

Configuration and Credentials

Configuration precedence:

1. Built-in defaults
2. ~/.klynx/config.toml
3. .klynx/config.toml
4. .klynx/tui/config.yaml (legacy TUI config)
5. Environment variables (for example KLYNX_DEFAULT_PROVIDER, KLYNX_DEFAULT_MODEL)
6. CLI overrides (-c key=value)

Credential lookup precedence:

1. Process environment variables
2. ~/.klynx/.env
3. .klynx/.env
4. Values written by klynx auth login

TUI Output Configuration

You can tune transcript visibility in .klynx/tui/config.yaml:

output:
  visible_events: [warning, error, answer, tool_exec]
  show_reasoning_indicator: true
  show_raw_stdout: false
  tool_result_max_lines: 8

Logging and Diagnostics

klynx run --log-level DEBUG --print-logs "debug this task"
klynx doctor --json

• Logs are written to ~/.klynx/logs/klynx-cli.log
• --print-logs also mirrors logs to stderr
• doctor checks import health, writable paths, tool availability, and auth readiness

Shell Completion

klynx completion bash
klynx completion powershell

PowerShell load example:

klynx completion powershell | Invoke-Expression

Exit Codes

• 0: success
• 1: runtime failure
• 2: usage error
• 3: config validation failure
• 4: session not found

Related Package

klynx-cli depends on the core SDK package klynx and installs it automatically via PyPI dependency resolution.