# Quickstart

> First successful invocation: `pip install hermes-okf`, `hermes-okf init`, write a concept, search it, and verify with `hermes-okf validate` — expected stdout signals and recovery when the bundle path is non-empty.

- Repository: EliaszDev/hermes-okf
- GitHub: https://github.com/EliaszDev/hermes-okf
- Human docs: https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02
- Complete Markdown: https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/llms-full.txt

## Source Files

- `README.md`
- `examples/basic_usage.py`
- `src/hermes_okf/cli.py`
- `src/hermes_okf/bundle.py`
- `tests/test_bundle.py`

---

---
title: "Quickstart"
description: "First successful invocation: `pip install hermes-okf`, `hermes-okf init`, write a concept, search it, and verify with `hermes-okf validate` — expected stdout signals and recovery when the bundle path is non-empty."
---

The `hermes-okf` entry point (`hermes_okf.cli:main`) operates on filesystem OKF bundles through `OKFBundle`: `init` materializes `index.md`, `log.md`, and seeded `projects/`, `decisions/`, and `context/` stubs; concept writes persist as `.md` files with YAML frontmatter; `search` runs token matching over title, description, and body via `SearchIndex`; and `validate` enforces reserved files plus a required `type` field on every non-reserved markdown file through `OKFValidator`.

## Prerequisites

| Requirement | Value |
|-------------|-------|
| Python | `>=3.9` (`pyproject.toml`) |
| Core dependency | `pyyaml>=6.0` only |
| CLI entry point | `hermes-okf` |

```bash
pip install hermes-okf
```

<Note>
Hermes plugin registration (`hermes-okf-install`) is a separate path. This page covers the standalone CLI bundle workflow only.
</Note>

## Initialise a bundle

`hermes-okf init` resolves the target path from the positional argument or `--path` (default `.`), rejects non-empty directories unless `--force` is set, then constructs `OKFBundle(path)` which creates the directory tree when missing.

<Steps>
<Step title="Create the bundle directory">

```bash
hermes-okf init ./knowledge
```

<RequestExample>

```bash
hermes-okf init ./knowledge
```

</RequestExample>

<ResponseExample>

```text
Initialised OKF bundle at /absolute/path/to/knowledge
```

</ResponseExample>

Exit code: `0`.

</Step>

<Step title="Confirm layout">

:::files
knowledge/
├── index.md          # okf_version frontmatter + directory links
├── log.md            # chronological agent log
├── projects/
│   └── index.md      # type: Directory
├── decisions/
│   └── index.md
└── context/
    └── index.md
:::

Reserved files `index.md` and `log.md` are excluded from concept validation. Subdirectory `index.md` stubs include `type: Directory` and pass `hermes-okf validate` immediately after init.

</Step>
</Steps>

### Global `--path` flag

Subcommands that accept `--path` default to the current directory. Both placements are equivalent:

```bash
hermes-okf validate --path ./knowledge
hermes-okf init ./knowledge
```

## Write a concept

The standalone CLI has no `write-concept` subcommand. Persist concepts through `OKFBundle.write_concept` (Python SDK) or by creating a `.md` file under the bundle root.

### Python SDK

Mirrors `examples/basic_usage.py`:

```python
from hermes_okf.bundle import OKFBundle

bundle = OKFBundle("./knowledge")
bundle.write_concept(
    "projects/my_project",
    body="# My Project\n\nDescribe your project here.",
    type="Project",
    title="My Project",
    tags=["ml", "data", "gpu"],
)
```

`write_concept` auto-inserts a UTC `timestamp` when omitted and writes `projects/my_project.md` with YAML frontmatter plus a markdown body.

### Manual markdown file

```bash
cat > ./knowledge/projects/my_project.md <<'EOF'
---
type: Project
title: My Project
tags:
  - ml
  - data
  - gpu
timestamp: 2026-06-15T19:25:46Z
---

# My Project

Describe your project here.
EOF
```

<Warning>
`OKFValidator` requires a `type` field in frontmatter on every `.md` file except `index.md` and `log.md`. `write_concept` does not enforce `type` at write time; missing `type` surfaces at `hermes-okf validate`.
</Warning>

## Search concepts

`hermes-okf search` builds an in-memory inverted index from `title`, `description`, and `body` tokens. Tags are not indexed.

```bash
hermes-okf search --path ./knowledge "project"
```

<RequestExample>

```bash
hermes-okf search --path ./knowledge "My Project"
```

</RequestExample>

<ResponseExample>

```text
1.00  projects/my_project
```

</ResponseExample>

| stdout | Meaning |
|--------|---------|
| `{score:.2f}  {concept_id}` | One result line; score is normalized token overlap |
| `No results.` | Query tokens matched no indexed text (exit `0`) |

<ParamField body="--top-k" type="integer" default="10">
Maximum result count.
</ParamField>

To find concepts by tag, use `OKFBundle.search_by_tag("gpu")` in Python rather than the CLI search command.

## Verify with validate

```bash
hermes-okf validate --path ./knowledge
```

### Success signal

<ResponseExample>

```text
Bundle is valid.
```

</ResponseExample>

Exit code: `0`.

### Failure signal

<ResponseExample>

```text
Found 1 validation error(s):
  - OKFValidationError(bad.md:1 -> Missing required 'type' field in frontmatter)
```

</ResponseExample>

Exit code: `1`. Each error line is the `repr` of an `OKFValidationError` with file path and message.

### Inspect a matched concept

```bash
hermes-okf show --path ./knowledge projects/my_project
```

Prints `ID`, `Type`, `Title`, `Tags`, `Timestamp`, optional `Resource`, then the markdown body.

## Non-empty bundle path recovery

`hermes-okf init` checks `path.exists() and any(path.iterdir())` before creating the bundle. A directory that already contains files is rejected without `--force`.

<RequestExample>

```bash
hermes-okf init ./existing-dir
```

</RequestExample>

<ResponseExample>

```text
Error: Directory './existing-dir' is not empty. Use --force to overwrite.
```

</ResponseExample>

Exit code: `1`.

### Recovery options

| Situation | Command | Behavior |
|-----------|---------|----------|
| Reuse directory, add OKF scaffold | `hermes-okf init ./existing-dir --force` | Calls `OKFBundle(path)`; creates missing `index.md`, `log.md`, and subdirectory stubs; does not delete existing files |
| Point CLI at an existing bundle | Skip `init`; pass `--path` on other subcommands | `OKFBundle` reopens without overwriting when `index.md` already exists |
| Fresh bundle at new path | `hermes-okf init ./new-knowledge` | Empty target directory only |

<ParamField body="--force" type="flag">
Bypass the non-empty directory guard on `init`. Does not truncate or remove pre-existing files in the target path.
</ParamField>

<Tip>
After `--force` init into a populated directory, run `hermes-okf validate --path <dir>` to confirm every non-reserved `.md` file (including pre-existing ones) has valid frontmatter with `type`.
</Tip>

## End-to-end command sequence

```bash
pip install hermes-okf
hermes-okf init ./knowledge
python -c "
from hermes_okf.bundle import OKFBundle
OKFBundle('./knowledge').write_concept(
    'projects/my_project',
    body='# My Project\n\nDescribe your project here.',
    type='Project', title='My Project', tags=['ml', 'data', 'gpu'],
)"
hermes-okf list --path ./knowledge
hermes-okf search --path ./knowledge "project"
hermes-okf validate --path ./knowledge
```

Expected stdout checkpoints:

| Step | Signal | Exit |
|------|--------|------|
| `init` | `Initialised OKF bundle at …` | `0` |
| `list` | `projects/my_project` | `0` |
| `search` | `1.00  projects/my_project` | `0` |
| `validate` | `Bundle is valid.` | `0` |

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
PyPI targets, optional `[rag]` and `[dev]` extras, entry-point scripts, and PATH recovery when `hermes-okf` is not found.
</Card>
<Card title="OKF bundle model" href="/okf-bundle-model">
Filesystem layout, `Concept` fields, reserved directories, and Hermes-native paths.
</Card>
<Card title="Standalone CLI workflows" href="/standalone-cli-workflows">
Full command surface beyond this minimal path: log append, graph inspection, snapshots, and context build.
</Card>
<Card title="Example: OKF bundle basics" href="/example-okf-bundle-basics">
Copy-paste Python recipe from `examples/basic_usage.py` with tag search and graph edges.
</Card>
<Card title="Install Hermes plugin" href="/install-hermes-plugin">
Register `hermes-okf` in `~/.hermes/plugins/` for `hermes okf` subcommands and automatic bundle creation.
</Card>
</CardGroup>