<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->

﻿---
title: Query the Knowledge Graph
description: Use the `knowledge:*` CLI subcommands on `elevasis-sdk` (external projects) and `elevasis` (monorepo) to browse, inspect, and traverse the OrganizationModel knowledge graph via six mount axes.
---

# Query the Knowledge Graph

The `knowledge:*` subcommands expose the OrganizationModel as a virtual filesystem. Paths are query strings -- `/by-system/sales/crm/` dispatches to a graph query, not a directory on disk. Three verbs cover all access patterns: `ls` (list), `cat` (read a node body), and `graph` (traverse edges).

Both CLIs share the same query layer (`@repo/core/knowledge/queries`). The only difference is which OrganizationModel they load:

- `elevasis-sdk` -- runs from inside `external/<project>/`, walks up to `.elevasis`, loads the project's `core/config/organization-model.ts`.
- `elevasis` -- runs from the monorepo root, loads `canonicalOrganizationModel` from `@repo/elevasis-core`.

## Before you start

The `knowledge:*` commands require `elevasis-sdk >= 1.4.0`. Check with:

```bash
pnpm exec elevasis-sdk --version
```

If you are running on Windows, **use PowerShell** for all `knowledge:*` commands. MSYS Bash rewrites the leading `/by-system/...` path argument to a Windows filesystem path, mangling the query. PowerShell passes the argument through verbatim.

## Three Verbs

| Verb                   | Behavior                                                                                                                    |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `knowledge:ls <path>`  | List nodes or edges for the mount. Default: id + summary table. `--json` for the wrapped envelope. `--ids-only` for piping. |
| `knowledge:cat <id>`   | Print a node's raw MDX `body` to stdout.                                                                                    |
| `knowledge:graph <id>` | Show outgoing and incoming edges for a node, grouped by edge kind.                                                          |

All three accept `--json` for machine-readable output. `knowledge:ls` additionally accepts `--ids-only` to print one node ID per line.

## Six Mount Axes

The path argument to `knowledge:ls` determines the query. Six axes are available:

| Path prefix                    | Query                           | Returns                                                     |
| ------------------------------ | ------------------------------- | ----------------------------------------------------------- |
| `/by-system/<dotted-id>/`      | `bySystem(graph, systemId)`     | nodes with incoming `governs` edges to this system          |
| `/by-ontology/<ontology-id>/`  | `byOntology(graph, ontologyId)` | nodes with incoming `governs` edges to this ontology record |
| `/by-kind/<kind>/`             | `byKind(graph, kind)`           | nodes where `node.kind === kind`                            |
| `/by-owner/<id>/`              | `byOwner(graph, ownerId)`       | nodes where `node.ownerIds.includes(id)`                    |
| `/graph/<nodeId>/governs/`     | `governs(graph, nodeId)`        | outgoing `governs` edges from `nodeId`                      |
| `/graph/<nodeId>/governed-by/` | `governedBy(graph, nodeId)`     | incoming `governs` edges to `nodeId`                        |

## Examples

Each example is shown for both CLIs.

### 1. List by system (`/by-system/<dotted-id>/`)

List all knowledge nodes that govern the `sales.crm` system:

```bash
# External project (from inside external/<project>/)
pnpm exec elevasis-sdk knowledge:ls /by-system/sales.crm/

# Monorepo (from monorepo root)
pnpm exec elevasis knowledge:ls /by-system/sales.crm/
```

Nested system ids use dots, not slashes: `sales.crm`, `sales.lead-gen`, `projects`.

### 2. List by ontology (`/by-ontology/<ontology-id>/`)

List all knowledge nodes that govern the CRM deal ontology record:

```bash
# External project
pnpm exec elevasis-sdk knowledge:ls /by-ontology/sales.crm:object/deal

# Monorepo
pnpm exec elevasis knowledge:ls /by-ontology/sales.crm:object/deal
```

Ontology IDs use `system.path:kind/local-id` or `global:kind/local-id`. Slash-containing ontology IDs are part of the query path; use PowerShell on Windows so the leading `/by-ontology/...` path is not rewritten by MSYS Bash.

### 3. List by kind (`/by-kind/<kind>/`)

List all nodes of kind `playbook`:

```bash
# External project
pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook

# Monorepo
pnpm exec elevasis knowledge:ls /by-kind/playbook
```

Common kinds: `playbook`, `strategy`, and `reference`. The available kinds are defined on `OrgKnowledgeNode.kind` in `@elevasis/core/knowledge`.

Machine-readable output for piping:

```bash
pnpm exec elevasis knowledge:ls /by-kind/playbook --ids-only
```

### 4. List by owner (`/by-owner/<id>/`)

List all knowledge nodes owned by a specific member or team:

```bash
# External project
pnpm exec elevasis-sdk knowledge:ls /by-owner/operations-team

# Monorepo
pnpm exec elevasis knowledge:ls /by-owner/operations-team
```

The `<id>` matches against `node.ownerIds`. Owner IDs are declared on each knowledge node in the OrganizationModel.

### 5. Traverse outgoing edges (`/graph/<nodeId>/governs/`)

List what a specific node governs (outgoing `governs` edges):

```bash
# External project
pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/

# Monorepo
pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
```

Knowledge node IDs use the `knowledge.<slug>` source id. Graph node IDs may be kind-prefixed,
such as `knowledge:knowledge.new-vertical-launch-playbook` or `system:sales.crm`, when traversing
graph edges.

> **Note:** Graph node IDs like `system:sales.crm` are addresses in the knowledge graph API and
> are distinct from the Organization Model `resource.systemPath` field. A resource attaches to a
> System with `systemPath: 'sales.crm'` (no prefix); the same System appears in the graph as the
> node `system:sales.crm`. Do not author `system:`-prefixed values into `resource.systemPath`.

### 6. Traverse incoming edges (`/graph/<nodeId>/governed-by/`)

List what governs a specific node (incoming `governs` edges):

```bash
# External project
pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/

# Monorepo
pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
```

## Read a Node Body

`knowledge:cat` prints the raw MDX `body` string for a node. The body is not rendered -- it is the source MDX as stored in the OrganizationModel.

```bash
# External project
pnpm exec elevasis-sdk knowledge:cat knowledge.new-vertical-launch-playbook

# Monorepo
pnpm exec elevasis knowledge:cat knowledge.new-vertical-launch-playbook
```

Pipe to a pager for long bodies:

```bash
pnpm exec elevasis knowledge:cat knowledge.platform-composition-patterns | less
```

## Inspect a Node's Edges

`knowledge:graph` shows all edges for a node grouped by kind:

```bash
# External project
pnpm exec elevasis-sdk knowledge:graph knowledge.new-vertical-launch-playbook

# Monorepo
pnpm exec elevasis knowledge:graph knowledge.new-vertical-launch-playbook
```

This combines the `governs` and `governed-by` views in one output, useful for understanding a node's full graph position.

## JSON Output

All three verbs accept `--json`. `knowledge:ls --json` uses the wrapped envelope format:

```json
{
  "path": "/by-system/sales.crm",
  "mount": "by-system",
  "args": ["sales.crm"],
  "results": [...]
}
```

This is the format consumed by the `/knowledge` agent skill. Use it when scripting or building tooling that reads knowledge graph data programmatically.

`knowledge:cat --json` returns the full knowledge node object, including the MDX `body`, links, owners, timestamps, and generated `sourceFilePath` when present.

`knowledge:graph --json` returns the same shape in both CLIs:

```json
{
  "nodeId": "knowledge.new-vertical-launch-playbook",
  "outgoing": [],
  "incoming": []
}
```

```bash
pnpm exec elevasis knowledge:ls /by-kind/playbook --json | jq '.results[].id'
```

## Windows Note

On Windows, MSYS Bash rewrites path arguments starting with `/` to Windows filesystem paths before the CLI sees them. Use PowerShell:

```powershell
# Correct on Windows -- PowerShell leaves the path arg intact
pnpm exec elevasis knowledge:ls /by-kind/playbook

# Wrong on Windows -- MSYS Bash mangles to C:\by-kind\playbook or similar
bash -c "pnpm exec elevasis knowledge:ls /by-kind/playbook"
```

All other `elevasis` and `elevasis-sdk` commands are unaffected; this gotcha is specific to path arguments that start with `/`.

## See Also

- [Query functions API](../reference/contracts.md) -- `bySystem`, `byOntology`, `byKind`, `byOwner`, `governs`, `governedBy` TypeScript signatures
- [Glossary](../reference/glossary.md) -- `systemId`, `nodeId`, `kind`, `ownerIds`
- [Knowledge Browser](../../../../apps/docs/content/docs/in-progress/active-development/sdk-changes/knowledge/index.mdx) -- task doc for the full Knowledge Map bundle
