CLI Guide¶

The Hyper-Knowledge CLI (hk) provides a powerful, easy-to-use interface for knowledge extraction directly from your terminal.

Installation¶

uv (recommended)pipx

uv tool install git+https://github.com/hanxiangmin/Hyper-Knowledge.git

pipx install git+https://github.com/hanxiangmin/Hyper-Knowledge.git

Verify installation:

hk --version

Quick Command Reference¶

Command	Purpose	Common Flags
`hk parse`	Extract knowledge from documents	`-t` template, `-o` output, `-l` language
`hk show`	Visualize knowledge graph	—
`hk export obsidian`	Export to an Obsidian vault	`-o` output, `--name`, `-f` force
`hk search`	Semantic search in knowledge abstract	`-n` top-k results
`hk talk`	Chat with knowledge abstract	`-i` interactive, `-q` query
`hk feed`	Add documents incrementally	—
`hk info`	Show knowledge abstract statistics	—
`hk build-index`	Build/rebuild search index	`-f` force rebuild
`hk clean`	Remove a KA's index (or the whole KA)	`-a` all, `-y` yes
`hk list`	List templates and methods	`template` or `method`
`hk config`	Manage configuration	`init`, `show`, `llm`, `embedder`

Complete Workflow¶

The typical workflow for extracting and interacting with knowledge:

flowchart TB
    subgraph Create ["🚀 Create"]
        D[📄 Document] -->|hk parse| KA[(💡 Knowledge Abstract)]
    end

    subgraph Enhance ["✨ Enhance (Optional)"]
        KA -->|hk feed| KA
        KA -->|hk build-index| IDX[(🔍 Index)]
    end

    subgraph Explore ["🔍 Explore"]
        KA -->|hk show| VIS[👁️ Visualize]
        IDX -->|hk search| SRCH[🔎 Search]
        IDX -->|hk talk| CHAT[💬 Chat]
    end

    subgraph Save ["💾 Save"]
        KA -->|hk dump| DISK[💾 Disk]
    end

Create — Extract knowledge from documents (hk parse)
Enhance — Add documents incrementally (hk feed), build index (hk build-index)
Explore — Visualize (hk show), search (hk search), chat (hk talk)
Save — Persist to disk (hk dump)

→ Detailed Workflow Walkthrough

Getting Started¶

1. Configure API Key¶

OpenAIBailian (Alibaba Cloud)DeepSeekAnthropic (Claude)Local vLLM

hk config init -p openai -k YOUR_OPENAI_API_KEY

hk config init -p bailian -k YOUR_BAILIAN_API_KEY

hk config llm -p deepseek -k YOUR_DEEPSEEK_API_KEY
hk config embedder -p openai -k YOUR_OPENAI_API_KEY

Anthropic provides LLM only — pair with an OpenAI-compatible embedder:

hk config llm -p anthropic -k YOUR_ANTHROPIC_API_KEY
hk config embedder -p openai -k YOUR_OPENAI_API_KEY

First install vLLM and start both services:

# Start LLM service (~8GB VRAM)
vllm serve Qwen/Qwen3.5-9B --port 8000 --api-key dummy

# Start Embedding service (~2GB VRAM)
vllm serve BAAI/bge-m3 --task embed --port 8001

Then configure Hyper-Knowledge:

hk config llm -p vllm \
  -u http://localhost:8000/v1 \
  -k dummy \
  -m Qwen/Qwen3.5-9B

hk config embedder -p vllm \
  -u http://localhost:8001/v1 \
  -k dummy \
  -m BAAI/bge-m3

Full deployment options (quantization, Docker, etc.) see Provider System.

2. Extract Knowledge¶

hk parse document.md -t general/biography_graph -o ./output/ -l en

3. Visualize¶

hk show ./output/

Commands in Detail¶

Knowledge Extraction¶

hk parse — Extract knowledge from documents
hk feed — Add documents to existing knowledge abstract

Exploration¶

hk show — Visualize knowledge graph
hk search — Semantic search
hk talk — Chat with knowledge abstract
hk info — View knowledge abstract statistics
hk export obsidian — Export to an Obsidian vault

Management¶

hk build-index — Build search index
hk clean — Remove a KA's index, or the whole KA
hk list — List available templates/methods
hk config — Configuration management

Configuration¶

The CLI stores configuration in ~/.hk/config.toml.

→ Configuration Reference

Template vs Method¶

Hyper-Knowledge offers two ways to extract knowledge:

Templates (Recommended for Most Users)¶

Domain-specific, ready-to-use configurations:

hk parse doc.md -t general/biography_graph -l en

Methods (Advanced)¶

Underlying extraction algorithms:

hk parse doc.md -m light_rag

→ Learn when to use each

Language Support¶

Templates support multiple languages:

# English
hk parse doc.md -t general/biography_graph -l en

# Chinese
hk parse doc.md -t general/biography_graph -l zh

Method templates always use English prompts.

Examples by Use Case¶

Research¶

# Extract from a research paper
hk parse paper.md -t general/concept_graph -o ./paper_kb/ -l en

# Ask questions about it
hk talk ./paper_kb/ -q "What are the main contributions?"

Biography Analysis¶

# Extract from a biography
hk parse biography.md -t general/biography_graph -o ./bio_kb/ -l en

# Visualize life events
hk show ./bio_kb/

Legal Document Analysis¶

# Extract contract obligations
hk parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l en

# Search for specific clauses
hk search ./contract_kb/ "termination conditions"

Tips and Best Practices¶

Use templates for domain-specific tasks — They're optimized for specific use cases
Build the index — Required for search and chat functionality
Feed incrementally — Add documents over time without reprocessing
Choose the right language — Improves extraction quality for non-English documents

Getting Help¶

View help for any command: hk <command> --help
List all templates: hk list template
List all methods: hk list method
FAQ
Troubleshooting