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

# 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. Every release is listed in the changelog.

Configure

# Global config with your YouTrack URL (recommended on first install).
kd init --global https://your-instance.youtrack.cloud

# The scaffolded connection reads its token from KD_TOKEN (its token_env).
export KD_TOKEN=perm:your-token-here

# Check the connection.
kd /system info

Create the token in YouTrack under Profile → Account Security → New token. In PowerShell, set it with $env:KD_TOKEN = "perm:your-token-here", or setx KD_TOKEN perm:your-token-here to keep it, then open a new terminal. token_cmd: in the connection reads the token from a command, such as a secrets manager, instead.

Global config lives at ~/.config/kd/config.yaml (Windows: C:\Users\<you>\.config\kd\config.yaml); kd init <url> without --global writes .kd/config.yaml in the current directory. KD_CONNECTION picks the connection by name.

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 FB
kd /article push guide.md --project FB --title "Setup Guide" --tag "type:guide"
kd /article pull FB-A-42 > setup.md

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

# 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:

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="FB")
results = client.search.search("router", types=["issue", "article"])

Development

pytest tests/ -v --tb=short

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

Updated: 2026-11-01