kg-cli 0.2.0

A knowledge graph CLI tool for managing structured information
Documentation

kg — local knowledge graph CLI

CI Release License

Beta - The tool is usable, but command details may still change.

kg helps you build a local knowledge graph from project docs, architecture notes, incidents, and system knowledge.

Use it when you want to:

  • keep one searchable graph per domain, project, or incident,
  • inspect concepts, processes, rules, bugs, decisions, and dependencies,
  • validate graph quality instead of storing loose notes,
  • let an AI assistant read and update the graph safely through MCP.

The default UX is for humans: readable terminal output, local files, no external service required.

Install

Option 1: installer script

curl -sSL https://raw.githubusercontent.com/nnar1o/kg/master/install.sh | sh

Option 2: crates.io

cargo install kg-cli

Option 3: from source

cargo install --path .

Check installation:

kg --version
kg --help

Quick start

Create a graph:

kg create fridge

Add a few nodes:

kg graph fridge node add concept:refrigerator --type Concept --name "Refrigerator" --description "Cooling appliance" --importance 5
kg graph fridge node add process:defrost --type Process --name "Defrost cycle" --description "Periodic ice removal cycle" --importance 4

Connect them:

kg graph fridge edge add concept:refrigerator DEPENDS_ON process:defrost --detail "requires periodic defrost"

Search and inspect:

kg graph fridge node find refrigerator
kg graph fridge node get concept:refrigerator --full
kg graph fridge stats --by-type --by-relation

Check graph quality:

kg graph fridge check
kg graph fridge quality missing-descriptions
kg graph fridge quality missing-facts

Main command pattern:

kg graph <graph-name> <command> [args...]

Examples:

kg graph fridge node find refrigerator --output-size 1200
kg graph fridge kql "node type=Concept sort=name limit=10"
kg graph fridge history

Build a graph from documentation

There are two practical ways to do this.

Option 1: import prepared Markdown files

If your docs are already normalized into Markdown files with YAML frontmatter, you can import them directly.

Example file:

---
id: concept:refrigerator
type: Concept
name: Refrigerator
description: Cooling appliance
provenance: docs
key_facts: ["Keeps food cold", "Has freezer compartment in some models"]
source_files: [manual.md]
---

Import:

kg create docs-demo
kg graph docs-demo import-md --path ./docs
kg graph docs-demo check --errors-only

See full format: docs/import-markdown.md

Option 2: use an LLM with kg-mcp on raw docs

This is the better option when you have raw architecture docs, specs, ADRs, runbooks, or mixed notes and want the AI to convert them into a clean graph.

  1. Start the MCP server:
kg-mcp
  1. Connect your AI client to kg-mcp.

Minimal config example:

{
  "mcpServers": {
    "kg": {
      "command": "/absolute/path/to/kg-mcp"
    }
  }
}
  1. Create an empty graph:
kg create payments
  1. Give your AI assistant the source documents and an explicit ingestion instruction.

Example prompt for an LLM connected to kg-mcp:

Build a knowledge graph from my project documentation using kg-mcp.

Graph name: payments
Scope: payment flow, retry rules, integrations, and datastore dependencies.
Sources:
- docs/payments/overview.md
- docs/payments/retries.md
- docs/payments/integrations.md

Rules:
1. Only add facts grounded in the provided documents.
2. Use stable IDs in the form <type>:<snake_case_name>.
3. Prefer a smaller correct graph over a larger speculative graph.
4. Work in batches of at most 10 nodes.
5. After each batch run:
   - kg graph payments check --errors-only
   - kg graph payments quality missing-descriptions
   - kg graph payments quality missing-facts
   Fix issues before continuing.
6. For each node include type, name, description, importance, and source reference when available.
7. Use notes for assumptions, not hard facts.
8. Do not delete existing nodes or edges unless I ask.

Workflow:
- First show me the extraction plan: candidate nodes, candidate edges, and ambiguous items.
- Wait for approval.
- Then create or update the graph batch by batch.
- At the end run:
  - kg graph payments stats --by-type --by-relation
  - kg graph payments node find "retry"
  - kg graph payments node get <2-3 critical node ids> --full
- Report what was added, remaining quality gaps, and which docs should be ingested next.

If you want a longer ready-to-copy version, use docs/ai-prompt-graph-from-docs.md.

If you want the full manual playbook, use docs/build-graph-from-docs.md.

Everyday commands

# list graphs
kg list --full

# inspect graph health
kg graph payments stats --by-type --by-relation
kg graph payments check --errors-only

# inspect nodes
kg graph payments node find "retry policy"
kg graph payments node get process:authorize_payment --full

# query with KQL
kg graph payments kql "node type=Process sort=name limit=20"

# export/import helpers
kg graph payments export-json --help
kg graph payments import-csv --help
kg graph payments import-md --help

AI / MCP usage

kg-mcp exposes the graph to an AI assistant over stdio, so the assistant can search, read, add, and validate graph data without direct shell access.

See full MCP reference: docs/mcp.md

FAQ

Should I use kg graph <name> ... or kg <name> ...?

Use kg graph <name> ... as the default pattern. The shorter form is only for backward compatibility.

What file format does kg use?

Default runtime prefers .kg. Older .json graphs can still be read, and the runtime may migrate them side by side.

What are .kgindex and .kglog?

They are helper sidecars for .kg graphs. kgindex speeds up node lookup and kglog stores lightweight search/feedback events.

Which output should I use in scripts?

Use --json in scripts and CI. Use the default text output in interactive terminal work.

A command fails with validation errors. What should I do?

Run:

kg graph <graph-name> check --errors-only

Fix the reported node or edge issues, then rerun your original command.

Documentation

Contact

For questions or feedback: nnar10@proton.me