# Standalone CLI reference

> All `hermes-okf` subcommands, global flags (`--version`, `--path`), per-command arguments (`--force`, `--json`, `--top-k`, `--note`, `--agent-id`, `--category`), exit codes, and stdout/error message shapes.

- 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`
- `pyproject.toml`
- `CHANGELOG.md`
- `README.md`
- `tests/test_bundle.py`

---

---
title: Standalone CLI reference
description: All hermes-okf subcommands, global flags (--version, --path), per-command arguments (--force, --json, --top-k, --note, --agent-id, --category), exit codes, and stdout/error message shapes.
---

The `hermes-okf` command is the standalone terminal interface for operating an OKF bundle without the Hermes agent runtime. It is registered as a console script in `pyproject.toml` and dispatches through `hermes_okf.cli:main`. Use it to initialise bundles, validate conformance, inspect concepts, search, append logs, traverse the knowledge graph, and run agent-adjacent operations (snapshots, context building, session/plan/tool listing).

For task-oriented examples, see [Standalone CLI workflows](/standalone-cli-workflows). For Hermes-integrated commands (`hermes okf …`), see [Hermes CLI reference](/hermes-cli-reference).

## Invocation

```bash
hermes-okf [--version] [-h]
hermes-okf <command> [command-args] [--path PATH]
```

When no subcommand is given, the CLI prints top-level help to stdout and exits `0`.

<RequestExample>

```bash
hermes-okf --version
```

</RequestExample>

<ResponseExample>

```
hermes-okf 0.4.6
```

</ResponseExample>

## Global flags

<ParamField body="--version" type="flag">
Print the installed package version (`hermes-okf {version}`) and exit. Implemented via argparse `action="version"`. Does not require a subcommand.
</ParamField>

<ParamField body="-h, --help" type="flag">
Print help for the root parser or the active subcommand, then exit `0`.
</ParamField>

<ParamField body="--path" type="string" default=".">
Path to the OKF bundle root directory. Shared across bundle-scoped subcommands via a `path_parent` parser (v0.4.6+). Expands `~` and resolves to an absolute path before use. Default is the current working directory.

Placement is flexible: `--path` may appear before or after the subcommand name and other flags.

```bash
hermes-okf validate --path ./knowledge
hermes-okf --path ./knowledge search "ffmpeg GPU"
```
</ParamField>

Commands **without** `--path`: `install-plugin`, `uninstall-plugin`.

### `init` path resolution

`init` accepts the bundle location through either a positional path or `--path`. The handler uses `init_path or path`:

```bash
hermes-okf init ./knowledge          # positional init_path
hermes-okf init --path ./knowledge     # --path only (v0.4.5+)
```

## Exit codes

| Code | When |
|------|------|
| `0` | Success; empty-but-valid results (`No concepts found.`, `No results.`, `Log is empty.`); root help with no subcommand; `install-plugin` / `uninstall-plugin` completion |
| `1` | Application errors: validation failures, missing concept, non-empty `init` target without `--force` |
| `2` | Argparse usage errors: unknown subcommand, missing required positional, invalid flag |

Uncaught Python exceptions (for example `ModuleNotFoundError` when `pyyaml` is missing) propagate as a traceback with a non-zero exit code (typically `1`).

## Subcommand reference

| Command | Bundle `--path` | Positional args | Notable flags |
|---------|-------------------|-----------------|---------------|
| `init` | Yes | `[init_path]` | `--force` |
| `validate` | Yes | — | — |
| `list` | Yes | — | `--subdir` |
| `show` | Yes | `concept_id` | `--json` |
| `search` | Yes | `query` | `--top-k` (default `10`) |
| `log` | Yes | — | — |
| `log-append` | Yes | `entry` | `--category` (default `Update`) |
| `graph-edges` | Yes | — | — |
| `graph-neighbors` | Yes | `concept_id` | — |
| `install-plugin` | No | — | — |
| `uninstall-plugin` | No | — | — |
| `snapshot` | Yes | — | `--note`, `--agent-id` (default `hermes`) |
| `context` | Yes | `query` | `--top-k` (default `5`), `--agent-id` (default `hermes`) |
| `sessions` | Yes | — | — |
| `plans` | Yes | — | — |
| `tools` | Yes | — | — |

---

### `init`

Initialise a new OKF bundle at the target path. Creates `index.md`, `log.md`, and seed subdirectories (`projects/`, `decisions/`, `context/`) when the bundle is new.

<ParamField body="init_path" type="string">
Optional positional bundle path. Takes precedence over `--path` when both are set.
</ParamField>

<ParamField body="--force" type="flag">
Bypass the non-empty directory guard. Does **not** delete or overwrite existing bundle files; `OKFBundle` skips re-initialisation when `index.md` already exists.
</ParamField>

<RequestExample>

```bash
hermes-okf init ./knowledge
hermes-okf init --path ~/.hermes/okf_memory
```

</RequestExample>

<ResponseExample>

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

</ResponseExample>

**Error (exit `1`):**

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

---

### `validate`

Run `OKFValidator` over the bundle: reserved files (`index.md`, `log.md`), frontmatter presence, YAML shape, and required `type` field on every concept `.md` file.

<RequestExample>

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

</RequestExample>

<ResponseExample>

Success:

```
Bundle is valid.
```

Failure:

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

</ResponseExample>

Each error line is the `repr()` of an `OKFValidationError` object (`file`, optional `line`, `message`). See [OKF validation reference](/okf-validation-reference) for the full rule set.

---

### `list`

Print concept IDs, one per line (relative paths without `.md`). Excludes `index.md` and `log.md`.

<ParamField body="--subdir" type="string">
Restrict listing to concepts under this subdirectory (for example `projects`).
</ParamField>

<RequestExample>

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

</RequestExample>

<ResponseExample>

```
projects/gpu
decisions/model_strategy
```

Empty bundle:

```
No concepts found.
```

</ResponseExample>

---

### `show`

Display a single concept by ID (for example `projects/my_project`, `config/agent`).

<ParamField body="concept_id" type="string" required>
Concept ID — bundle-relative path without `.md`.
</ParamField>

<ParamField body="--json" type="flag">
Emit the full `Concept` dataclass as indented JSON (`asdict`, `default=str`) instead of the human-readable layout.
</ParamField>

<RequestExample>

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

</RequestExample>

<ResponseExample>

Human-readable (default):

```
ID:         projects/gpu
Type:       Project
Title:      GPU Project
Tags:       ffmpeg, gpu
Timestamp:  2026-06-15T19:27:38Z

# GPU Project

Use ffmpeg with GPU acceleration.
```

`Resource:` is printed only when `concept.resource` is set.

JSON (`--json`):

```json
{
  "id": "projects/gpu",
  "type": "Project",
  "title": "GPU Project",
  "description": "",
  "tags": ["ffmpeg", "gpu"],
  "resource": null,
  "timestamp": "2026-06-15T19:27:38Z",
  "body": "# GPU Project\n\nUse ffmpeg with GPU acceleration.",
  "metadata": { "type": "Project", "title": "GPU Project", "tags": ["ffmpeg", "gpu"] }
}
```

Not found (exit `1`):

```
Concept 'nonexistent' not found.
```

</ResponseExample>

---

### `search`

Full-text search via `SearchIndex` over concept title, description, and body. Results are ranked by relevance score.

<ParamField body="query" type="string" required>
Search query string.
</ParamField>

<ParamField body="--top-k" type="integer" default="10">
Maximum number of results to return.
</ParamField>

<RequestExample>

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

</RequestExample>

<ResponseExample>

```
1.00  projects/gpu
0.50  decisions/model_strategy
```

Format: `{score:.2f}  {concept_id}` — score left-aligned to two decimal places, two spaces, then concept ID.

No matches:

```
No results.
```

</ResponseExample>

---

### `log`

Print the full contents of `log.md` to stdout.

<RequestExample>

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

</RequestExample>

<ResponseExample>

```
# Agent Log


## 2026-06-15
* **Decision**: Chose GPU path
```

Empty log:

```
Log is empty.
```

</ResponseExample>

---

### `log-append`

Append a dated entry to `log.md` via `OKFBundle.append_log`.

<ParamField body="entry" type="string" required>
Log entry text.
</ParamField>

<ParamField body="--category" type="string" default="Update">
Entry category label (for example `Decision`, `Observation`, `Tool-Call`). Rendered as `* **{category}**: {entry}` under the current date heading.
</ParamField>

<RequestExample>

```bash
hermes-okf log-append --path ./knowledge "New decision made" --category Decision
```

</RequestExample>

<ResponseExample>

```
Log entry added.
```

</ResponseExample>

---

### `graph-edges`

List all directed edges extracted from markdown links in concept files.

<RequestExample>

```bash
hermes-okf graph-edges --path ./knowledge
```

</RequestExample>

<ResponseExample>

```
a -> b  (other)
projects/gpu -> decisions/model_strategy  (see also)
```

Format: `{source} -> {target}  ({context})` where `context` is the link label. External `http` links are excluded.

Empty graph:

```
No edges found.
```

</ResponseExample>

---

### `graph-neighbors`

Print outgoing neighbor concept IDs for a given source concept.

<ParamField body="concept_id" type="string" required>
Source concept ID.
</ParamField>

<RequestExample>

```bash
hermes-okf graph-neighbors --path ./knowledge projects/gpu
```

</RequestExample>

<ResponseExample>

```
decisions/model_strategy
context/env
```

One target ID per line. Empty:

```
No neighbors found.
```

</ResponseExample>

---

### `snapshot`

Save agent state snapshot to `snapshots/{timestamp}` via `HermesAgent.snapshot`. Creates a `Snapshot` concept with JSON state (agent ID, model, session, plan, system prompt, note).

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

<ParamField body="--agent-id" type="string" default="hermes">
Agent identifier passed to `HermesAgent`.
</ParamField>

<RequestExample>

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

</RequestExample>

<ResponseExample>

```
Snapshot saved.
```

</ResponseExample>

The standalone CLI does not expose `restore`; use `hermes okf restore` or the Python SDK. See [Hermes CLI reference](/hermes-cli-reference).

---

### `context`

Build a markdown context string for LLM prompts via `HermesAgent.build_context`. Combines system prompt, active plan, relevant memory (`recall` with `top_k`), recent log lines, and registered tools.

<ParamField body="query" type="string" required>
Query to rank relevant concepts against.
</ParamField>

<ParamField body="--top-k" type="integer" default="5">
Number of relevant concepts to include in the **Relevant Memory** section.
</ParamField>

<ParamField body="--agent-id" type="string" default="hermes">
Agent identifier passed to `HermesAgent`.
</ParamField>

<RequestExample>

```bash
hermes-okf context --path ./knowledge "What should I prioritize?"
```

</RequestExample>

<ResponseExample>

```markdown
# Agent Context: hermes

## System Prompt

You are a helpful, autonomous Hermes agent.

## Relevant Memory

- **GPU Project** (Project): # GPU Project

Use ffmpeg with GPU acceleration.

## Recent Activity

```
# Agent Log

## 2026-06-15
* **Decision**: Chose GPU path
```

## Available Tools

- `search_web` — Search the web for information
```

Sections are omitted when empty (no active plan, no tools, etc.). Output is printed verbatim to stdout with no trailing status line.
</ResponseExample>

---

### `sessions`

List session concept IDs from the `sessions/` subdirectory, sorted chronologically. Uses a fixed `HermesAgent` with `agent_id="hermes"`.

<RequestExample>

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

</RequestExample>

<ResponseExample>

```
sessions/2026-06-14T22-14-58Z
sessions/2026-06-15T10-30-00Z
```

Empty: prints nothing (exit `0`).
</ResponseExample>

---

### `plans`

List concept IDs under the `plans/` subdirectory via `bundle.list_concepts("plans")`.

<RequestExample>

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

</RequestExample>

<ResponseExample>

```
plans/refactor_auth_2026-06-15
```

Empty:

```
No active plans.
```

</ResponseExample>

---

### `tools`

List registered tool concept IDs from `HermesAgent.list_tools()` (`tools/` subdirectory).

<RequestExample>

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

</RequestExample>

<ResponseExample>

```
tools/search_web
tools/run_shell
```

Empty: prints nothing (exit `0`).
</ResponseExample>

---

### `install-plugin`

Install the Hermes plugin wrapper to `~/.hermes/plugins/hermes-okf/` and optionally update `~/.hermes/config.yaml`. Delegates to `hermes_okf.install_plugin.install_plugin`. Does not accept `--path`.

<RequestExample>

```bash
hermes-okf install-plugin
```

</RequestExample>

<ResponseExample>

```
Installed hermes-okf plugin to /home/user/.hermes/plugins/hermes-okf
  Updated ~/.hermes/config.yaml
  Run 'hermes memory setup' to finish activation
```

When config is unchanged:

```
Installed hermes-okf plugin to /home/user/.hermes/plugins/hermes-okf
  Run 'hermes memory setup' to activate
```

</ResponseExample>

Equivalent standalone entry point: `hermes-okf-install`. See [Install Hermes plugin](/install-hermes-plugin).

---

### `uninstall-plugin`

Remove `~/.hermes/plugins/hermes-okf/`. Does not delete the OKF bundle. Always exits `0`.

<RequestExample>

```bash
hermes-okf uninstall-plugin
```

</RequestExample>

<ResponseExample>

```
Removed hermes-okf plugin from /home/user/.hermes/plugins/hermes-okf
```

Or when not installed:

```
hermes-okf plugin not installed
```

</ResponseExample>

Equivalent standalone entry point: `hermes-okf-uninstall`.

---

## Argparse error shapes

Invalid subcommand (exit `2`, stderr):

```
hermes-okf: error: argument command: invalid choice: 'invalid-cmd' (choose from 'init', 'validate', ...)
```

Missing required positional (exit `2`, stderr):

```
usage: hermes-okf show [-h] [--path PATH] [--json] concept_id
hermes-okf show: error: the following arguments are required: concept_id
```

## Bundle auto-creation note

Most bundle-scoped commands construct `OKFBundle(args.path)`. If the path does not exist, `OKFBundle` creates the directory and initialises a minimal conformant structure. Prefer `hermes-okf init` for explicit setup; use `validate` to confirm an existing bundle. See [OKF bundle model](/okf-bundle-model).

## Related pages

<CardGroup>
<Card title="Standalone CLI workflows" href="/standalone-cli-workflows">
Task-oriented recipes for init, validate, search, log, graph, snapshot, and context without Hermes.
</Card>
<Card title="Hermes CLI reference" href="/hermes-cli-reference">
`hermes okf` subcommands (`search`, `list --type`, `show --raw`, `snapshot`, `restore`) registered via the Hermes plugin.
</Card>
<Card title="Installation" href="/installation">
PyPI install, optional extras, and entry-point scripts (`hermes-okf`, `hermes-okf-install`, `hermes-okf-uninstall`).
</Card>
<Card title="OKF validation reference" href="/okf-validation-reference">
`OKFValidator` rules and the error object shape behind `validate` output.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Recovery when commands are not found, bundles are missing, or plugin install fails.
</Card>
</CardGroup>