# CLI reference

> Complete `he` command surface: `parse`, `feed`, `build-index`, `search`, `talk`, `show`, `info`, `list template`, `list method`, `config` subcommands, flags, defaults, exit conditions, and input/output contracts.

- Repository: yifanfeng97/Hyper-Extract
- GitHub: https://github.com/yifanfeng97/Hyper-Extract
- Human docs: https://grok-wiki.com/public/docs/yifanfeng97-hyper-extract-7891c7254cdf
- Complete Markdown: https://grok-wiki.com/public/docs/yifanfeng97-hyper-extract-7891c7254cdf/llms-full.txt

## Source Files

- `hyperextract/cli/cli.py`
- `hyperextract/cli/commands/config.py`
- `hyperextract/cli/commands/list.py`
- `hyperextract/cli/README.md`
- `hyperextract/cli/utils.py`
- `pyproject.toml`

---

---
title: CLI reference
description: Complete `he` command surface — subcommands, flags, defaults, exit conditions, and input/output contracts for Hyper-Extract.
---

The `he` binary is the Hyper-Extract command-line interface. It is registered in `pyproject.toml` as `he = "hyperextract.cli:app"` and requires **Python 3.11+**. All extraction, search, and chat commands that call an LLM or embedder invoke `validate_config()` before proceeding; `info` and `list` commands do not.

## Global behavior

Running `he` with no subcommand prints a branded overview of available commands and exits **0**. Global options apply to every invocation.

<ParamField body="--version" type="flag" default="false">
Print package version (`Hyper-Extract CLI version …`) and exit **0**. Eager option — evaluated before subcommands.
</ParamField>

<ParamField body="HYPER_EXTRACT_LOG_LEVEL" type="env var" default="WARNING">
Controls structlog verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`). There is no `--verbose` flag.
</ParamField>

<ParamField body="HYPER_EXTRACT_LOG_FILE" type="env var">
Optional file path for log output in addition to stderr.
</ParamField>

<RequestExample>

```bash
he                    # Overview banner
he --version          # Print version
he --help             # Typer-generated help
```

</RequestExample>

## Command map

| Command | Purpose | Requires config | Requires KA |
|---------|---------|-----------------|-------------|
| `he parse` | Create a new Knowledge Abstract (KA) | Yes | — |
| `he feed` | Append documents to an existing KA | Yes | `metadata.json` |
| `he build-index` | Build or rebuild vector index | Yes | `data.json` |
| `he search` | Semantic search | Yes | `data.json` + `index/` |
| `he talk` | Q&A chat | Yes | `data.json` + `index/` |
| `he show` | Visualize via OntoSight | Yes | `data.json` |
| `he info` | Print KA statistics | No | `data.json` |
| `he list template` | List YAML templates | No | — |
| `he list method` | List extraction methods | No | — |
| `he config …` | Manage LLM/embedder settings | No | — |

## Knowledge Abstract I/O contract

Commands that read or write a KA expect a directory with this layout:

:::files
```
<ka_path>/
├── data.json        # Structured extraction output (required for most commands)
├── metadata.json    # template, lang, timestamps (required for feed)
└── index/           # FAISS vector store (required for search/talk)
```
:::

<ResponseField name="data.json" type="object">
Serialized AutoType payload. `he info` counts `nodes`/`entities` and `edges`/`relations` for dict-shaped data, or list length for array-shaped data.
</ResponseField>

<ResponseField name="metadata.json" type="object">
Fields used by the CLI: `template`, `lang`, `created_at`, `updated_at`. `feed` and reload commands resolve template from metadata; preset templates use IDs like `general/biography_graph`, custom templates may reference a local `{template}.yaml` in the KA directory.
</ResponseField>

<ResponseField name="index/" type="directory">
Non-empty directory of vector-index files. Created by `he parse` (unless `--no-index`) or `he build-index`.
</ResponseField>

---

## `he parse`

Extract knowledge from text into a **new** KA directory.

<ParamField body="input" type="string" required>
File path, directory path, or `-` for stdin (UTF-8). Directories are scanned for `*.txt` and `*.md` only; files are concatenated with `\n\n`.
</ParamField>

<ParamField body="--output / -o" type="string" required>
Output KA directory. Created if missing.
</ParamField>

<ParamField body="--template / -t" type="string">
Template ID (e.g. `general/biography_graph`). Omit for interactive selection.
</ParamField>

<ParamField body="--method / -m" type="string">
Shorthand for method templates. Sets template to `method/{name}` (e.g. `-m light_rag` → `method/light_rag`). Takes precedence over interactive selection when set.
</ParamField>

<ParamField body="--lang / -l" type="string">
`zh` or `en`. **Required** for knowledge (YAML) templates. Ignored for method templates — language is forced to `en`.
</ParamField>

<ParamField body="--force / -f" type="flag" default="false">
Overwrite a non-empty output directory.
</ParamField>

<ParamField body="--no-index" type="flag" default="false">
Skip `build_index()` after extraction. Use `he build-index` later to enable `search`/`talk`.
</ParamField>

<Steps>
<Step title="Validate prerequisites">

`validate_config()` must pass. For knowledge templates, `--lang` must be supplied. For method templates, `--lang` is optional and ignored.

</Step>
<Step title="Resolve template">

If neither `-t` nor `-m` is given, an interactive picker lists all gallery templates. `-m` maps to `method/{method}`.

</Step>
<Step title="Extract and persist">

`Template.create(template, lang)` → `feed_text(text)` → `dump(output)`. Unless `--no-index`, also runs `build_index()` and dumps again.

</Step>
</Steps>

<RequestExample>

```bash
# Knowledge template (language required)
he parse document.md -o my_ka -t general/biography_graph -l en

# Method template (language optional, forced to en)
he parse document.md -o my_ka -m light_rag

# Directory of markdown files
he parse ./docs/ -o my_ka -t general/graph -l zh

# Stdin
cat article.md | he parse - -o my_ka -t general/graph -l en

# Skip indexing
he parse doc.md -o my_ka -t general/graph -l en --no-index
```

</RequestExample>

**Exit conditions**

| Code | Condition |
|------|-----------|
| **0** | Extraction and save succeeded |
| **1** | Missing config; no template selected; missing `--lang` for knowledge template; non-empty output without `--force`; template not found; directory has no `.txt`/`.md` files; `FileNotFoundError` on input |

---

## `he feed`

Append knowledge to an **existing** KA. Does **not** rebuild the search index — run `he build-index` afterward if you need updated search results.

<ParamField body="ka_path" type="string" required>
Existing KA directory with `metadata.json`.
</ParamField>

<ParamField body="input" type="string" required>
File path or `-` for stdin.
</ParamField>

<ParamField body="--template / -t" type="string">
Override template. Default: `metadata.template`, falling back to `general/graph`.
</ParamField>

<ParamField body="--lang / -l" type="string">
Override language. Default: `metadata.lang`, falling back to `zh`.
</ParamField>

<RequestExample>

```bash
he feed my_ka new_section.md
he feed my_ka - < additional.txt
```

</RequestExample>

**Exit conditions**

| Code | Condition |
|------|-----------|
| **0** | Knowledge appended and `data.json` updated |
| **1** | Invalid config; KA path invalid; missing `metadata.json`; template resolution failed; input file not found |

---

## `he build-index`

Build or rebuild the FAISS vector index for semantic search and chat.

<ParamField body="ka_path" type="string" required>
KA directory containing `data.json`.
</ParamField>

<ParamField body="--force / -f" type="flag" default="false">
Clear existing index and rebuild. Without `--force`, an existing non-empty `index/` prints a warning and exits **0** without changes.
</ParamField>

<RequestExample>

```bash
he build-index my_ka
he build-index my_ka --force   # Rebuild after he feed
```

</RequestExample>

**Exit conditions**

| Code | Condition |
|------|-----------|
| **0** | Index built, or index already exists (no `--force`) |
| **1** | Invalid config; KA missing `data.json`; load/build/save error |

---

## `he search`

Run semantic search against an indexed KA.

<ParamField body="ka_path" type="string" required>
KA directory with non-empty `index/`.
</ParamField>

<ParamField body="query" type="string" required>
Natural-language search query.
</ParamField>

<ParamField body="--top-k / -n" type="integer" default="3">
Number of results to return.
</ParamField>

<ResponseField name="stdout" type="text">
Rich-formatted result blocks. Pydantic models are printed as indented JSON via `model_dump()`; other objects print as strings. Empty results print `No results found.`
</ResponseField>

<RequestExample>

```bash
he search my_ka "key findings"
he search my_ka "revenue growth" -n 5
```

</RequestExample>

**Exit conditions**

| Code | Condition |
|------|-----------|
| **0** | Search completed (including zero results) |
| **1** | Invalid config; KA or index missing; load/search error |

---

## `he talk`

Chat with an indexed KA using retrieval-augmented generation.

<ParamField body="ka_path" type="string" required>
KA directory with non-empty `index/`.
</ParamField>

<ParamField body="--query / -q" type="string">
Single-turn question. Required unless `--interactive` is set.
</ParamField>

<ParamField body="--top-k / -n" type="integer" default="3">
Number of context items retrieved per query.
</ParamField>

<ParamField body="--interactive / -i" type="flag" default="false">
Enter a REPL loop. Type `exit`, `quit`, or `q` to leave; `Ctrl+C` also exits gracefully.
</ParamField>

<ResponseField name="stdout" type="text">
Single-query mode prints `response.content`. If `response.additional_kwargs["retrieved_items"]` is present, truncated previews of retrieved context are printed below the answer.
</ResponseField>

<RequestExample>

```bash
he talk my_ka -q "What was the main topic?"
he talk my_ka -i
```

</RequestExample>

**Exit conditions**

| Code | Condition |
|------|-----------|
| **0** | Query answered or interactive session ended normally |
| **1** | Invalid config; KA or index missing; neither `-q` nor `-i` provided; load/chat error |

---

## `he show`

Visualize a KA using OntoSight. Opens an interactive graph view in the default environment (browser or embedded viewer depending on OntoSight configuration).

<ParamField body="ka_path" type="string" required>
KA directory containing `data.json`.
</ParamField>

<RequestExample>

```bash
he show my_ka
```

</RequestExample>

**Exit conditions**

| Code | Condition |
|------|-----------|
| **0** | Visualization launched successfully |
| **1** | KA missing or no `data.json`; config invalid; load or visualization error |

---

## `he info`

Print KA metadata and statistics. Does not require LLM/embedder configuration.

<ParamField body="ka_path" type="string" required>
KA directory containing `data.json`.
</ParamField>

<ResponseField name="stdout" type="table">
Rich table with: Path, Template, Language, Created, Updated, Nodes, Edges, Index status (`Built` / `Not Built`).
</ResponseField>

<RequestExample>

```bash
he info my_ka
```

</RequestExample>

**Exit conditions**

| Code | Condition |
|------|-----------|
| **0** | Info displayed |
| **1** | KA path invalid or `data.json` missing |

---

## `he list template`

List available YAML knowledge templates and, by default, method templates.

<ParamField body="--query / -q" type="string">
Keyword filter on template ID or description.
</ParamField>

<ParamField body="--autotype / -a" type="string">
Filter by AutoType (`graph`, `hypergraph`, `list`, `model`, `set`, etc.).
</ParamField>

<ParamField body="--lang / -l" type="string" default="en">
Language for descriptions: `en`, `zh`, or `all` (lists every supported language variant).
</ParamField>

<ParamField body="--include-methods / --no-methods" type="flag" default="true">
Include `method/*` entries. Method templates are excluded when `--lang zh` is set.
</ParamField>

<RequestExample>

```bash
he list template
he list template -l zh
he list template -a graph -q finance
he list template --no-methods
```

</RequestExample>

**Exit conditions:** always **0** (prints `No templates found.` when the filter matches nothing).

---

## `he list method`

List registered extraction methods (`graph_rag`, `light_rag`, `hyper_rag`, etc.).

<ParamField body="--query / -q" type="string">
Keyword filter on method name or description.
</ParamField>

<RequestExample>

```bash
he list method
he list method -q rag
```

</RequestExample>

**Exit conditions:** always **0**.

---

## `he config`

Manage LLM and embedder settings stored in `~/.he/config.toml`. Running `he config` with no subcommand prints a configuration overview and exits **0**.

<Tabs>
<Tab title="init">

Interactive or one-shot setup for both LLM and embedder.

<ParamField body="--provider / -p" type="string">
Preset: `openai`, `bailian`, `vllm`.
</ParamField>

<ParamField body="--api-key / -k" type="string">
API key. With `--provider`, configures both services. Without `--provider`, defaults to OpenAI (`gpt-4o-mini` + `text-embedding-3-small`).
</ParamField>

<ParamField body="--base-url / -u" type="string">
Custom API base URL. Required for `vllm`; optional override for other presets.
</ParamField>

```bash
he config init                                    # Interactive wizard
he config init -k sk-...                          # OpenAI quick setup
he config init -p bailian -k sk-...              # Provider preset
he config init -p vllm -k dummy -u http://localhost:8000/v1
```

</Tab>
<Tab title="show">

```bash
he config show
```

Prints a table of LLM and embedder provider, model, masked API key, and base URL.

</Tab>
<Tab title="llm">

<ParamField body="--provider / -p" type="string">
`openai`, `bailian`, `vllm`
</ParamField>

<ParamField body="--api-key / -k" type="string">
LLM API key
</ParamField>

<ParamField body="--model / -m" type="string">
Model name (default in file: `gpt-4o-mini`)
</ParamField>

<ParamField body="--base-url / -u" type="string">
Custom base URL
</ParamField>

<ParamField body="--show" type="flag">
Display current LLM config only
</ParamField>

<ParamField body="--unset" type="flag">
Reset LLM section to defaults
</ParamField>

```bash
he config llm -k sk-... -m gpt-4o
he config llm --show
he config llm --unset
```

</Tab>
<Tab title="embedder">

Same flags as `llm`. Default model in file: `text-embedding-3-small`.

```bash
he config embedder -k sk-... -m text-embedding-3-small
he config embedder --show
he config embedder --unset
```

</Tab>
</Tabs>

### Configuration validation

Commands that call `validate_config()` check resolved settings (config file merged with environment):

| Provider | LLM requirement | Embedder requirement |
|----------|-----------------|----------------------|
| `vllm` | `base_url` required; API key may be `dummy` | `base_url` required; API key may be `dummy` |
| Other | API key required (or `OPENAI_API_KEY` env) | API key required (or `OPENAI_API_KEY` env) |

<ParamField body="OPENAI_API_KEY" type="env var">
Fallback API key when not set in `config.toml`.
</ParamField>

<ParamField body="OPENAI_BASE_URL" type="env var">
Fallback base URL when not set in `config.toml`.
</ParamField>

Provider presets and default models:

| Preset | Default LLM | Default embedder | Base URL |
|--------|-------------|------------------|----------|
| `openai` | `gpt-4o-mini` | `text-embedding-3-small` | `https://api.openai.com/v1` |
| `bailian` | `qwen3.6-plus` | `text-embedding-v4` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `vllm` | user-specified | user-specified | user-specified |

**Exit conditions:** subcommands exit **0** on success. `validate_config()` failures in other commands exit **1** with a remediation message.

---

## Typical workflows

<Steps>
<Step title="First run">

```bash
he config init
he list template -l en
```

</Step>
<Step title="Create and query">

```bash
he parse examples/en/tesla.md -o tesla_ka -t general/biography_graph -l en
he show tesla_ka
he search tesla_ka "alternating current"
he talk tesla_ka -q "What did Tesla invent?"
```

</Step>
<Step title="Evolve knowledge">

```bash
he feed tesla_ka new_chapter.md
he build-index tesla_ka --force
he info tesla_ka
```

</Step>
</Steps>

## Exit code summary

| Code | Meaning |
|------|---------|
| **0** | Success, informational exit, or no-op warning (`build-index` when index exists) |
| **1** | Validation failure, missing input/output, template resolution error, or runtime exception |
| **≠ 0** | Unrecognized global flags (e.g. removed `--verbose`) |

<AccordionGroup>
<Accordion title="Interactive template picker (`he parse` without `-t`/`-m`)">

Prompts for a number (1-based index) or search keyword. Keyword search matches template ID or description; a single match is auto-selected, multiple matches are listed for re-entry. Default selection is `1`. Exits **1** if the gallery is empty or the user aborts without a selection.

</Accordion>
<Accordion title="Stdin and encoding">

`read_input("-")` reads all of `sys.stdin`. File inputs are opened as UTF-8. Missing files raise `FileNotFoundError` (surfaced as a Python traceback unless caught upstream).

</Accordion>
<Accordion title="Custom templates in KA directories">

When reloading a KA, template resolution checks gallery presets first, then looks for `{template}.yaml` inside the KA directory. This supports custom templates copied during `he parse` from a local `.yaml` path.

</Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
<Card title="Configure providers" href="/configure-providers">
Set up LLM and embedder clients before running extraction commands.
</Card>
<Card title="Extract and evolve" href="/extract-and-evolve">
Workflow guide for `parse`, `feed`, and `build-index`.
</Card>
<Card title="Search, chat, and visualize" href="/search-chat-visualize">
Query and explore Knowledge Abstracts with `search`, `talk`, `show`, and `info`.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
Full `~/.he/config.toml` schema and environment variable precedence.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Common CLI failure modes and debug logging.
</Card>
<Card title="Python API reference" href="/python-api-reference">
SDK equivalents for every CLI lifecycle operation.
</Card>
</CardGroup>