# Standalone CLI workflows

> Operate an OKF bundle without Hermes: init, validate, list/show concepts, full-text search, log append, graph inspection, snapshot, context build, and session/plan/tool listing with `--path` placement rules.

- 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

- `src/hermes_okf/cli.py`
- `README.md`
- `src/hermes_okf/search.py`
- `src/hermes_okf/graph.py`
- `src/hermes_okf/hermes.py`
- `tests/test_search.py`

---

---
title: "Standalone CLI workflows"
description: "Operate an OKF bundle without Hermes: init, validate, list/show concepts, full-text search, log append, graph inspection, snapshot, context build, and session/plan/tool listing with `--path` placement rules."
---

The `hermes-okf` entry point (`hermes_okf.cli:main`) operates directly on filesystem OKF bundles through `OKFBundle`, `SearchIndex`, `GraphExtractor`, and `OKFValidator`. Agent-oriented subcommands (`snapshot`, `context`, `sessions`, `tools`) delegate to `HermesAgent`, which bootstraps the Hermes-native layout (`config/`, `sessions/`, `plans/`, `tools/`, `snapshots/`) inside the bundle. No Hermes runtime or model provider is required.

<Info>
Standalone CLI and the Hermes plugin share the same bundle format. Commands here read and write the same `.md` + YAML files that `hermes okf` uses when the plugin is installed.
</Info>

## Prerequisites

Install the package and confirm the CLI is on `PATH`:

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

For a minimal first bundle, see [Quickstart](/quickstart). For bundle layout and reserved files, see [OKF bundle model](/okf-bundle-model).

## Bundle path (`--path`) placement

Most subcommands inherit a shared `--path` flag via a parent parser. The flag can appear **after the subcommand name** alongside subcommand-specific arguments.

<ParamField body="--path" type="string" default=".">
Root directory of the OKF bundle. Expanded with `expanduser()` and resolved to an absolute path before use.
</ParamField>

| Rule | Behavior |
|------|----------|
| Default | Current working directory (`.`) |
| Placement | After subcommand: `hermes-okf search "query" --path ./knowledge` |
| `init` precedence | Positional `init_path` wins over `--path`: `args.init_path or args.path` |
| No `--path` | `install-plugin`, `uninstall-plugin` (Hermes registration only) |

<CodeGroup>
```bash title="Explicit path after subcommand"
hermes-okf list --path ./knowledge
hermes-okf show projects/my_project --path ./knowledge
```

```bash title="Default path (cwd is the bundle)"
cd ./knowledge
hermes-okf list
hermes-okf validate
```

```bash title="init with positional path"
hermes-okf init ./knowledge
hermes-okf init --path ./knowledge   # equivalent when positional omitted
```
</CodeGroup>

<Warning>
`install-plugin` and `uninstall-plugin` do not accept `--path`. They modify `~/.hermes/plugins/` and config — see [Install Hermes plugin](/install-hermes-plugin).
</Warning>

## Command map

```text
hermes-okf [--version]
├── init [path] [--force] [--path]
├── validate [--path]
├── list [--subdir SUBDIR] [--path]
├── show CONCEPT_ID [--json] [--path]
├── search QUERY [--top-k N] [--path]
├── log [--path]
├── log-append ENTRY [--category CAT] [--path]
├── graph-edges [--path]
├── graph-neighbors CONCEPT_ID [--path]
├── snapshot [--note NOTE] [--agent-id ID] [--path]
├── context QUERY [--top-k N] [--agent-id ID] [--path]
├── sessions [--path]
├── plans [--path]
├── tools [--path]
├── install-plugin
└── uninstall-plugin
```

Agent commands (`snapshot`, `context`, `sessions`, `tools`) construct a `HermesAgent` at the bundle path. First invocation creates `config/agent`, starts a session, and ensures `config/`, `sessions/`, `plans/`, `tools/`, and `snapshots/` exist.

## Initialise a bundle

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

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

`OKFBundle` creates `index.md`, `log.md`, and seed subdirectories `projects/`, `decisions/`, and `context/` each with an `index.md` stub.

<ResponseExample>
```text
Initialised OKF bundle at /absolute/path/to/knowledge
```
</ResponseExample>

</Step>

<Step title="Handle a non-empty target directory">

If the directory exists and is not empty, init exits with code `1` unless `--force` is passed:

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

<ResponseExample>
```text
Error: Directory './knowledge' is not empty. Use --force to overwrite.
```
</ResponseExample>

`--force` does not delete existing files; it allows init to proceed when the directory already has content.

</Step>

<Step title="Validate structure">

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

<ResponseExample>
```text
Bundle is valid.
```
</ResponseExample>

See [OKF validation reference](/okf-validation-reference) for rule details.

</Step>
</Steps>

## Add and inspect concepts

The standalone CLI has no `write` subcommand. Create concepts with the Python SDK, a text editor, or another tool that writes `.md` files with YAML frontmatter.

<Steps>
<Step title="Write a concept (SDK)">

```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", "gpu"],
)
```

Every concept file needs a `type` field in frontmatter. `write_concept` auto-adds a UTC `timestamp` when omitted.

</Step>

<Step title="List concept IDs">

```bash
hermes-okf list --path ./knowledge
hermes-okf list --subdir projects --path ./knowledge
```

Prints one concept ID per line (relative path without `.md`). Skips reserved `index.md` and `log.md`.

<ResponseExample>
```text
projects/my_project
```
</ResponseExample>

Empty bundle:

<ResponseExample>
```text
No concepts found.
```
</ResponseExample>

</Step>

<Step title="Show a concept">

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

Human-readable output includes `ID`, `Type`, `Title`, `Tags`, `Timestamp`, optional `Resource`, then the markdown body. `--json` emits the full `Concept` dataclass as JSON.

Missing concept exits `1`:

<ResponseExample>
```text
Concept 'projects/missing' not found.
```
</ResponseExample>

</Step>
</Steps>

## Search concepts

`search` uses `SearchIndex`: an in-memory inverted index built on first query, tokenizing lowercase alphanumeric words from `title`, `description`, and `body`.

```bash
hermes-okf search "ffmpeg GPU" --path ./knowledge
hermes-okf search "machine learning" --top-k 5 --path ./knowledge
```

<ParamField body="--top-k" type="integer" default="10">
Maximum number of `(concept_id, score)` pairs to return.
</ParamField>

<ResponseExample>
```text
1.00  projects/my_project
0.50  decisions/gpu_choice
```
</ResponseExample>

Scores are token-match counts normalized by query length. No matches:

<ResponseExample>
```text
No results.
```
</ResponseExample>

<Tip>
For vector retrieval over the same bundle, install `hermes-okf[rag]` and follow [Enable RAG](/enable-rag). The standalone `search` command uses only the standard library.
</Tip>

## Log operations

The bundle's chronological history lives in `log.md`.

```bash
# Read full log
hermes-okf log --path ./knowledge

# Append an entry
hermes-okf log-append "Chose PyTorch over JAX" --category Decision --path ./knowledge
```

<ParamField body="--category" type="string" default="Update">
Prefix label for the log line. Common values: `Decision`, `Observation`, `Plan`.
</ParamField>

`append_log` groups entries under `## YYYY-MM-DD` date headings. Each line is `* **{category}**: {entry}`.

<ResponseExample>
```text
Log entry added.
```
</ResponseExample>

## Graph inspection

Edges come from markdown links `[text](target)` inside concept files. HTTP links are excluded.

```bash
# All directed edges
hermes-okf graph-edges --path ./knowledge

# Outgoing neighbors of one concept
hermes-okf graph-neighbors projects/my_project --path ./knowledge
```

<ResponseExample>
```text
projects/my_project -> decisions/gpu_choice  (see decision)
```
</ResponseExample>

For tag clustering, BFS traversal, and NetworkX export, use `GraphExtractor` in the Python SDK — see [Knowledge graph](/knowledge-graph).

## Snapshot and context build

These commands instantiate `HermesAgent(bundle_path, agent_id)` and operate on agent state stored in the bundle.

### Save a snapshot

```bash
hermes-okf snapshot --path ./knowledge --note "Before deployment"
hermes-okf snapshot --agent-id my-agent --note "Checkpoint" --path ./knowledge
```

<ParamField body="--note" type="string" default="">
Free-text note stored in the snapshot concept metadata.
</ParamField>

<ParamField body="--agent-id" type="string" default="hermes">
Agent identifier written into snapshot metadata and used for session structure.
</ParamField>

Writes a `snapshots/{timestamp}` concept (`type: Snapshot`) containing JSON state: `agent_id`, `model`, `current_session`, `current_plan`, `system_prompt`, `note`.

<ResponseExample>
```text
Snapshot saved.
```
</ResponseExample>

<Note>
Standalone CLI has no `restore` subcommand. Restoration is available via `hermes okf restore` when the Hermes plugin is installed, or through `HermesAgent.restore()` in the SDK.
</Note>

### Build LLM context

```bash
hermes-okf context "What should I prioritize?" --path ./knowledge
hermes-okf context "GPU decisions" --top-k 3 --agent-id hermes --path ./knowledge
```

<ParamField body="--top-k" type="integer" default="5">
Number of relevant concepts from `memory.recall()` to include in the context block.
</ParamField>

`build_context` assembles markdown sections:

1. Agent ID header
2. System prompt from `config/agent`
3. Active plan body (if `current_plan_id` is set)
4. Relevant memory (search-ranked concepts)
5. Recent log (last 20 lines)
6. Available tools from `tools/` directory

Output is printed to stdout as a single markdown document suitable for pasting into an LLM prompt.

## List sessions, plans, and tools

| Command | Backend | Default agent ID | Output |
|---------|---------|------------------|--------|
| `sessions` | `HermesAgent.list_sessions()` | `hermes` (hardcoded) | Session IDs under `sessions/`, sorted |
| `plans` | `OKFBundle.list_concepts("plans")` | n/a | Active plan concept IDs |
| `tools` | `HermesAgent.list_tools()` | `hermes` (hardcoded) | Tool concept IDs under `tools/` |

```bash
hermes-okf sessions --path ./knowledge
hermes-okf plans --path ./knowledge
hermes-okf tools --path ./knowledge
```

Empty results:

<ResponseExample>
```text
No active plans.
```
</ResponseExample>

<Warning>
`sessions` and `tools` always use agent ID `hermes`, regardless of `--agent-id`. Only `snapshot` and `context` accept `--agent-id`. To inspect state for a custom agent ID, use the Python SDK or write concepts directly.
</Warning>

## End-to-end workflow

<Steps>
<Step title="Bootstrap">

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

</Step>

<Step title="Populate concepts">

Use the SDK or edit files manually. Ensure each `.md` concept has valid YAML frontmatter with `type`.

</Step>

<Step title="Verify and explore">

```bash
hermes-okf validate --path ./knowledge
hermes-okf list --path ./knowledge
hermes-okf search "project" --path ./knowledge
hermes-okf show projects/my_project --path ./knowledge
```

</Step>

<Step title="Record activity">

```bash
hermes-okf log-append "Initial setup complete" --category Observation --path ./knowledge
hermes-okf graph-edges --path ./knowledge
```

</Step>

<Step title="Agent state (optional)">

```bash
hermes-okf snapshot --note "Baseline" --path ./knowledge
hermes-okf context "summarize project status" --path ./knowledge
hermes-okf sessions --path ./knowledge
hermes-okf plans --path ./knowledge
hermes-okf tools --path ./knowledge
```

</Step>
</Steps>

## Exit codes and stdout conventions

| Condition | Exit code | Message shape |
|-----------|-----------|---------------|
| Success (including empty results) | `0` | Informational stdout |
| `init` on non-empty dir without `--force` | `1` | `Error: Directory '...' is not empty...` |
| `validate` with errors | `1` | `Found N validation error(s):` + per-error lines |
| `show` concept missing | `1` | `Concept '...' not found.` |
| No subcommand | `0` | Prints top-level help |

Validation errors print `OKFValidationError` representations including file path and message.

## Failure modes

<AccordionGroup>
<Accordion title="validate reports missing type field">

Every concept `.md` except reserved `index.md` and `log.md` must have YAML frontmatter with a `type` key. Fix the file or regenerate via `write_concept`.

</Accordion>

<Accordion title="search returns no results but concepts exist">

`SearchIndex` tokenizes lowercase alphanumeric substrings. Hyphenated or camelCase terms may not match as expected. Try shorter keywords or use SDK `fuzzy_search` (optional `rapidfuzz`).

</Accordion>

<Accordion title="graph-edges shows no edges">

Edges require markdown links between concepts: `[label](other_concept)` or `[label](other_concept.md)`. Plain text references do not create edges.

</Accordion>

<Accordion title="snapshot/context creates unexpected directories">

`HermesAgent` ensures `config/`, `sessions/`, `plans/`, `tools/`, and `snapshots/` on first use and starts a session. This is expected standalone behavior, not a Hermes-plugin side effect.

</Accordion>

<Accordion title="plans lists archived or completed plans">

`plans` lists all concept IDs under the `plans/` subdirectory, including active and completed plans not yet archived to `plans/archive/`.

</Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Standalone CLI reference" href="/standalone-cli-reference">
Complete subcommand, flag, and exit-code reference for every `hermes-okf` command.
</Card>

<Card title="Quickstart" href="/quickstart">
Install, init, write a concept, search, and validate in one pass.
</Card>

<Card title="OKF bundle model" href="/okf-bundle-model">
Filesystem layout, `Concept` fields, reserved files, and Hermes-native directories.
</Card>

<Card title="Example: OKF bundle basics" href="/example-okf-bundle-basics">
Python SDK recipe mirroring the CLI workflows above.
</Card>

<Card title="Install Hermes plugin" href="/install-hermes-plugin">
Register `hermes-okf` with Hermes for `hermes okf` subcommands and `restore`.
</Card>
</CardGroup>