kd-cli 2.0.4

Knowledge dispatcher for live knowledge systems

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

# pipx (recommended)
pipx install kd

# or uv
uv tool install kd

Configure

# 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

# 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

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

pytest tests/ -v --tb=short

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

---

Updated: 2026-04-13