# `openclaw path`

Plugin-provided shell access to the `oc://` addressing substrate — one universal,

kind-dispatched path scheme for inspecting and surgically editing workspace

files (markdown, jsonc, jsonl). Self-hosters and editor extensions use

it to read or write a single leaf inside a workspace file without scripting

against the SDK directly.

Plugin-provided shell access to the `oc://` addressing substrate: one

kind-dispatched path scheme for inspecting and editing addressable workspace

files (markdown, jsonc, jsonl). Self-hosters, plugin authors, and editor

extensions use it to read, find, or update a narrow location without

hand-rolling per-file parsers.

The CLI mirrors the substrate's public verbs:

- `resolve` is concrete and single-match.

- `find` is the multi-match verb for wildcards, unions, predicates, and

positional expansion.

- `set` only accepts concrete paths or insertion markers; wildcard patterns are

rejected before writing.

`path` is provided by the bundled optional `oc-path` plugin. Enable it before

first use:

| Subcommand | Purpose |

| ----------------------- | ---------------------------------------------------------------------------- |

| `resolve <oc-path>` | Print the match at the path (or "not found"). |

| `find <pattern>` | Enumerate matches for a wildcard / predicate path. |

| `set <oc-path> <value>` | Write a leaf at the path. Supports `--dry-run`. |

| `validate <oc-path>` | Parse-only — print structural breakdown (file / section / item / field). |

| `resolve <oc-path>` | Print the concrete match at the path (or "not found"). |

| `find <pattern>` | Enumerate matches for a wildcard / union / predicate path. |

| `set <oc-path> <value>` | Write a leaf or insertion target at a concrete path. Supports `--dry-run`. |

| `validate <oc-path>` | Parse-only; print structural breakdown (file / section / item / field). |

| `emit <file>` | Round-trip a file through `parseXxx` + `emitXxx` (byte-fidelity diagnostic). |

## Global flags

oc://FILE/SECTION/ITEM/FIELD?session=SCOPE

```

Slot rules — `field` requires `item`, `item` requires `section`. Across all

Slot rules: `field` requires `item`, and `item` requires `section`. Across all

four slots:

- **Quoted segments** — `"a/b.c"` survives `/` and `.` separators.

- **Ordinal** — `#N` for Nth match by document order.

- **Insertion markers** — `+`, `+key`, `+nnn` for keyed / indexed

insertion (use with `set`).

- **Session scope** — `?session=cron:daily` etc. Orthogonal to slot

nesting.

- **Session scope** — `?session=cron-daily` etc. Orthogonal to slot

nesting. Session values are raw, not percent-decoded; they may not contain

control characters or reserved query delimiters (`?`, `&`, `%`).

Reserved characters (`?`, `&`, `%`) outside quoted, predicate, or union

segments are rejected. Control characters (U+0000–U+001F, U+007F) are

rejected anywhere.

segments are rejected. Control characters (U+0000-U+001F, U+007F) are rejected

anywhere, including the `session` query value.

`formatOcPath(parseOcPath(path)) === path` is guaranteed for canonical paths.

Non-canonical query parameters are ignored except for the first non-empty

`session=` value.

## Addressing by file kind

| Kind | Addressing model |

| ---------- | -------------------------------------------------------------------------------- |

| Markdown | H2 sections by slug, bullet items by slug or `#N`, frontmatter via `[frontmatter]`. |

| JSONC/JSON | Object keys and array indexes; dots split nested sub-segments unless quoted. |

| JSONL | Top-level line addresses (`L1`, `L2`, `$last`), then JSONC-style descent inside the line. |

`resolve` returns a structured match: `root`, `node`, `leaf`, or

`insertion-point`, with a 1-based line number. Leaf values are surfaced as text

plus a `leafType` so plugin authors can render previews without depending on

the per-kind AST shape.

## Mutation contract

`set` writes one concrete target:

- Markdown frontmatter values and `- key: value` item fields are string leaves.

Markdown insertions append sections, frontmatter keys, or section items and

render a canonical markdown shape for the changed file.

- JSONC leaf writes coerce the string value to the existing leaf type

(`string`, finite `number`, `true`/`false`, or `null`). JSONC object and array

insertions parse `<value>` as JSON and use the `jsonc-parser` edit path for

ordinary leaf writes, preserving comments and nearby formatting.

- JSONL leaf writes coerce like JSONC inside a line. Whole-line replacement and

append parse `<value>` as JSON. Rendered JSONL preserves the file's dominant

LF/CRLF line-ending convention.

Use `--dry-run` before user-visible writes when the exact bytes matter. The

substrate preserves byte-identical output for parse/emit round-trips, but a

mutation can canonicalize the edited region or file depending on kind.

## Examples

openclaw path emit ./AGENTS.md

```

More grammar examples:

```bash

# Quote keys containing / or .

openclaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias'

# Predicate search over JSONC children

openclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id'

# Insert into a JSONC array

openclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run

# Insert a JSONC object key

openclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run

# Append a JSONL event

openclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl

# Resolve the last JSONL value line

openclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl

# Address markdown frontmatter

openclaw path resolve 'oc://AGENTS.md/[frontmatter]/name'

# Insert markdown frontmatter

openclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run

# Find markdown item fields

openclaw path find 'oc://SKILL.md/Tools/*/send_email'

# Validate a session-scoped path

openclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

```

## Exit codes

| Code | Meaning |

## Notes

- `set` writes raw bytes through the substrate's emit path, which applies the

- `set` writes bytes through the substrate's emit path, which applies the

redaction-sentinel guard automatically. A leaf carrying

`__OPENCLAW_REDACTED__` (verbatim or as a substring) is refused at write

time.