Metadata-Version: 2.4
Name: kd-cli
Version: 2.1.3
Summary: Knowledge Dispatcher for issue trackers and knowledge bases
Author: Sergiy Gladkyy
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/kd-cli/
Project-URL: Issues, https://github.com/IntellectSolutionsCom/kd-cli/issues
Project-URL: Source, https://github.com/IntellectSolutionsCom/kd-cli
Project-URL: Changelog, https://github.com/IntellectSolutionsCom/kd-cli/blob/main/CHANGELOG.md
Keywords: youtrack,cli,sdk,knowledge-management,knowledge-network
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: packaging>=23.0
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

**Knowledge Dispatcher.** A command-line and Python tool for accessing and managing information that lives in issue trackers and knowledge bases — designed to be equally natural for humans and large language models.

Today kd speaks **YouTrack**. On the roadmap: **JIRA**, **GitHub Issues**, **GitLab**, and possibly **Obsidian**. One tool, one set of verbs, many backends.

## What kd does

- **Full issue CRUD from the terminal or a script.** Create, update, comment, link, time-log, assign, query — no web UI round-trips, no ad-hoc REST glue.
- **Knowledge-base article workflows.** Idempotent `push` from local markdown, `pull` as markdown for editing, moves across projects, tag-driven queries. Articles round-trip cleanly through an HTML-comment marker so repeated LLM-driven edits preserve upstream identity instead of creating duplicates.
- **Cross-project visibility via tokens.** kd sees exactly what the token's connection permits on the upstream server — nothing more, nothing less. Access control stays upstream where it belongs, not in a parallel local config.
- **Cross-entity search** spanning issues and articles in a single query.
- **Structured output** (JSON, YAML, table, markdown) because the primary consumer is often another program — an LLM, a shell pipeline, a CI job — not a human eyeballing a terminal.

## The primer — and why it exists

The **primer** (`kd /primer`) is the centerpiece: a small, workspace-local file of pinned references and curated notes that every kd session can surface on demand.

It exists to solve a problem that has gotten worse as LLMs have become central to real work:

- **Visible memory.** Agentic tools accumulate hidden "memories" in opaque per-LLM buckets you cannot easily read, edit, or audit. The primer is a plain file you can open, version, and review. If an LLM appears to "remember" something load-bearing, you can see exactly where that came from.
- **LLM-portable.** One primer works for any model. Switch from Claude to GPT-5 to the next generation — the primer travels with the project, not with a vendor.
- **Shared by humans and LLMs.** A developer jotting "on this project the sprint field is called `Board`" in the primer is building the same artifact an LLM would build, in the same place, readable by both. No separate convention to maintain.
- **A routing layer, not a copy.** The primer can pin real knowledge-base articles (`kd /primer/article add FB-A-42`). It never duplicates their content — it points at them. The rest of kd extends this shape: pull what the current task needs from live systems, reason, push updates back. Nothing gets mirrored into a parallel store.

## What kd is not

- **Not a migration platform.** Cross-system moves are deliberate lossy cherry-picks — a stub on the target side with a backref to the source, not a faithful reproduction.
- **Not a data warehouse.** Data lives in the upstream tracker; kd sits on top.
- **Not a faithful replica.** kd reads what a task needs and writes what actually changed. It never claims to be a complete mirror.

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

## Install

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

# or uv
uv tool install kd-cli
```

The PyPI distribution name is `kd-cli` (two-letter `kd` is reserved by PyPI policy). The installed command, the import name, and the CLI entry point are all `kd`.

Release notes for the installed version: `kd /release-notes`. The canonical changelog lives at [`kd/resources/CHANGELOG.md`](kd/resources/CHANGELOG.md).

## 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 (workspace 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

The CLI is a thin wrapper over a Python library. Same capabilities, programmatic interface:

```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"])
```

## Development

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

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

---
Updated: 2026-04-14
