Metadata-Version: 2.4
Name: klynx-cli
Version: 0.0.3
Summary: Klynx Textual CLI application package.
Author-email: QZX <qzx480@gmail.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: klynx>=0.0.15
Requires-Dist: textual>=0.70.0
Requires-Dist: pyte>=0.8.2
Requires-Dist: python-dotenv>=1.0.0

﻿# 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)

```bash
pip install -U klynx-cli
```

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

```bash
playwright install chromium
```

## Quick Start (5 Minutes)

### 1) Configure your model API key

```bash
klynx auth login --model gpt-4o
```

Or set environment variables manually (example):

```bash
export OPENAI_API_KEY="sk-..."
```

### 2) Launch the interactive TUI

```bash
klynx
```

### 3) Run one task immediately

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

### 4) Run in headless mode

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

### 5) Resume the latest session

```bash
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:

```bash
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:

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

### Tutorial D: Manage session history

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

## Common Commands

```bash
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`:

```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

```bash
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

```bash
klynx completion bash
klynx completion powershell
```

PowerShell load example:

```powershell
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.
