Metadata-Version: 2.4
Name: kd-cli
Version: 2.0.4
Summary: Knowledge dispatcher for live knowledge systems
Author: Sergiy Gladkyy
License-Expression: MIT
Keywords: youtrack,cli,sdk,knowledge-management,knowledge-network
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tabulate>=0.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-tabulate; extra == "dev"
Dynamic: license-file

# kd

A knowledge dispatcher for live knowledge systems — pull what you need to reason, push your updates back, and stay on top of a live system rather than copying it.

## Purpose

**kd is a knowledge-network tool, not a data-exchange tool.** It is built around a small, primer-shaped idea: the operator reasons *on top of* live trackers, not alongside copies of them. The primary loop is **pull → reason → push updates back**. Integrating multiple sources happens in the operator's head — not in kd's data model. Occasional cross-system moves exist, but they are deliberately thin: at the limit, a stub with a similar title and a backref to the original, not a faithful reproduction. kd is not a migration tool or a comprehensive import-export platform; it is a network-of-knowledge dispatcher that speaks YouTrack fluently and will, over time, speak other trackers through narrow domain protocols.

The **primer** (`kd /primer`) is the working illustration: a small set of pinned references plus curated notes, living in the workspace, sitting on top of live systems without replacing them. The rest of the tool extends that shape.

**SDK-first**: the Python library (`kd.client`) is the primary interface; CLI commands are thin wrappers over it. LLMs constructing commands programmatically are the primary consumer, so syntax clarity and structured output matter more than keystroke economy.

## Install

```bash
# pipx (recommended)
pipx install kd

# or uv
uv tool install kd
```

## Configure

```bash
# Scaffold a project-local config in the current directory.
kd init

# Or set via environment (overrides workspace + global config).
export KD_TOKEN=your_token
export KD_CONNECTION=main
```

Global config lives at `~/.config/kd/config.yaml`; workspace config lives at `.kd/config.yaml`.

## Usage

### CLI

```bash
# Projects
kd /project list
kd /project show FB

# Issues
kd /issue list --project FB --query "#Unresolved"
kd /issue create "Fix router configuration" -p FB --type Task
kd /issue show FB-1

# Time tracking
kd /time log FB-1 45 --type Development --description "Router reconfiguration"

# Articles
kd /article list --project CMCSA
kd /article push guide.md --project CMCSA --title "Setup Guide" --tag "type:guide"
kd /article pull FB-A-42 > setup.md

# Tags
kd /tag list
kd /tag articles type:case --project CMCSA

# Saved queries
kd /query list
kd /query issues "Sprint 47" --project FB

# Primer (local knowledge, LLM context)
kd /primer/note add "Sprint field is called 'Board'"
kd /primer/article add FB-A-42 --summary "Architecture Overview"
kd /primer show

# Cross-entity search
kd /search "router" --types issue,article --project FB

# Output formats
kd /project list --output json | jq '.[].key'
kd /issue list --output yaml
```

### Python SDK

```python
from kd import YouTrackClient

client = YouTrackClient(
    url="https://your-instance.youtrack.cloud",
    token="your_token",
)

projects = client.projects.list()
issue = client.issues.create(project="FB", summary="Fix router config")
client.time.log(issue_id="FB-1", minutes=45, work_type="Development")
articles = client.tags.articles(["type:case"], project="CMCSA")
results = client.search.search("router", types=["issue", "article"])
```

## What kd is not

- **Not a migration platform.** Cross-system moves are lossy cherry-picks: a stub on the target side with a backref to the source, nothing more.
- **Not a faithful mirror.** kd never claims to be a complete copy of upstream state; it reads what it needs and writes what changed.
- **Not a data warehouse.** Data lives in the upstream tracker; kd sits on top.

If you need a migration tool or an import-export platform, kd is the wrong tool.

## Development

```bash
pytest tests/ -v --tb=short

ruff format kd/ tests/
ruff check --fix kd/ tests/
mypy kd/
```

---
Updated: 2026-04-13
