Path

remoteclaw path

Shell access to the oc:// addressing scheme: one kind-dispatched path syntax for inspecting and editing addressable workspace files (markdown, jsonc, jsonl, yaml/yml/lobster). Self-hosters, plugin authors, and editor extensions use it to read, find, or update a narrow location without hand-rolling a per-file parser.

path is provided by the bundled optional oc-path plugin. Enable it before first use:

remoteclaw plugins enable oc-path

The CLI verbs mirror the addressing model:

• 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.
• validate parses a path with no filesystem access.
• emit round-trips a file through parse + emit (byte-fidelity diagnostic).

Why use it

RemoteClaw state is spread across human-edited markdown, commented JSONC config, append-only JSONL logs, and YAML workflow/spec files. Scripts, hooks, and agents often need one small value from those files: a frontmatter key, a plugin setting, a log record field, a YAML step, or a bullet item under a named section.

remoteclaw path gives those callers a stable address instead of a one-off grep, regex, or parser per file kind. The same oc:// path can be validated, resolved, searched, dry-run, and written from the terminal, which keeps narrow automation reviewable and replayable. It preserves the rest of the file, so writing one leaf does not disturb its comments, line endings, or nearby formatting.

Use it when the thing you want has a logical address, but the file shape varies:

• A hook reads one setting from commented JSONC without losing comments when it writes the value back.
• A maintenance script finds every matching event field in a JSONL log without loading the whole log into a custom parser.
• An editor jumps to a markdown section or bullet item by slug, then renders the exact line it resolved to.
• An agent dry-runs a small workspace edit before applying it, with the changed bytes visible in review.

Skip remoteclaw path for ordinary whole-file edits, rich config migrations, or memory-specific writes; those should use the owner command or plugin. path is for small, addressable file operations where a repeatable terminal command beats another bespoke parser.

How it is used

Read one value from a human-edited config file:

remoteclaw path resolve 'oc://config.jsonc/plugins/github/enabled'

Preview a write without touching disk:

remoteclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

Find matching records in an append-only JSONL log:

remoteclaw path find 'oc://session.jsonl/[event=tool_call]/name'

Address an instruction in markdown by section and item instead of by line number:

remoteclaw path resolve 'oc://AGENTS.md/runtime-safety/remoteclaw-gateway'

Validate a path in CI or a preflight script before the script reads or writes:

remoteclaw path validate 'oc://AGENTS.md/tools/$last/risk'

These commands are meant to be copyable into shell scripts. Use --json when a caller needs structured output and --human when a person is inspecting the result.

How it works

1. Parses the oc:// address into slots: file, section, item, field, and an optional session query.
2. Chooses the file-kind adapter from the target extension (.md, .jsonc, .json, .jsonl, .ndjson, .yaml, .yml, .lobster).
3. Resolves the slots against that file kind’s structure: markdown headings/items, JSONC object keys/array indexes, JSONL line records, or YAML map/sequence nodes.
4. For set, emits edited bytes through the same adapter so untouched parts of the file keep their comments, line endings, and nearby formatting where the kind supports it.

resolve and set require one concrete target. find is the exploratory verb: it expands wildcards, unions, predicates, and ordinals into the concrete matches you can inspect before choosing one to write.

Subcommands

Subcommand	Purpose
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 the structural breakdown (file / section / item / field).
emit <file>	Round-trip a file through parse + emit (byte-fidelity diagnostic).

Global flags

Flag	Applies to	Purpose
--cwd <dir>	resolve, find, set, emit	Resolve the file slot against this directory (default: process.cwd()).
--file <path>	resolve, find, set, emit	Override the file slot’s resolved path (absolute access).
--json	all	Force JSON output (default when stdout is not a TTY).
--human	all	Force human output (default when stdout is a TTY).
--value-json	set	Parse <value> as JSON for JSON/JSONC/JSONL leaf replacement.
--dry-run	set	Print the bytes that would be written without writing.
--diff	set (requires --dry-run)	Print a unified diff instead of the full bytes.

validate takes only --json / --human; it does no filesystem access, so --cwd and --file do not apply.

oc:// syntax

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

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

• Quoted segments — "a/b.c" survives / and . separators. Content is byte-literal; " and \ are not allowed inside quotes. The file slot is also quote-aware: oc://"skills/email-drafter"/Tools/$last treats skills/email-drafter as a single file path.
• Predicates — [k=v], [k!=v], [k<v], [k<=v], [k>v], [k>=v]. Numeric operators require both sides to coerce to finite numbers.
• Unions — {a,b,c} matches any of the alternatives.
• Wildcards — * (single sub-segment) and ** (zero-or-more, recursive). find accepts these; resolve and set reject them as ambiguous.
• Positional — $first / $last resolve to the first / last index or declared key.
• Ordinal — #N for the 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 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, 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.

Hard limits: a path caps at 4096 bytes, at most 4 slots (file/section/item/ field), at most 64 dotted sub-segments per slot, and at most 256 nested traversal levels for deep JSON paths. Separately, any JSONC/JSON file input over 16 MiB is refused with a parse diagnostic instead of being parsed, for any verb that loads that file.

Addressing by file kind

Kind	File extensions	Addressing model
Markdown	.md	H2 sections by slug, bullet items by slug or #N, frontmatter via [frontmatter].
JSONC/JSON	.jsonc, .json	Object keys and array indexes; dots split nested sub-segments unless quoted.
JSONL	.jsonl, .ndjson	Top-level line addresses (L1, L2, $first, $last), then JSONC-style descent inside the line.
YAML/.lobster	.yaml, .yml, .lobster	Map keys and sequence indexes; comments and flow style are handled by the YAML document API.

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. Section bodies are not writable as a whole through set.
• JSONC leaf writes coerce the string value to the existing leaf type (string, finite number, true/false, or null). Use --value-json when a JSONC/JSON/JSONL leaf replacement should parse <value> as JSON and may change shape, such as replacing a string secret-ref shorthand with an object. 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 (majority vote across the file’s newlines, so a mostly-CRLF file stays CRLF even with a few stray LFs).
• YAML leaf writes coerce to the existing scalar type (string, finite number, true/false, or null). YAML insertions use the bundled yaml package’s document API for map/sequence updates. Malformed YAML documents with parser errors are refused before mutation with parse-error.

Use --dry-run before user-visible writes when the exact bytes matter. JSONC and YAML edits patch the existing document (via jsonc-parser or the yaml document API), so untouched bytes usually survive; markdown rebuilds the file from its parsed structure on any edit, which can normalize incidental formatting outside the changed leaf. Add --diff when you want the preview as a focused before/after patch instead of the full rendered file.

Examples

# Validate a path (no filesystem access)
remoteclaw path validate 'oc://AGENTS.md/Tools/$last/risk'

# Read a leaf
remoteclaw path resolve 'oc://gateway.jsonc/version'

# Wildcard search
remoteclaw path find 'oc://session.jsonl/*/event' --file ./logs/session.jsonl

# Dry-run a write
remoteclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run

# Dry-run a write as a unified diff
remoteclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run --diff

# Apply the write
remoteclaw path set 'oc://gateway.jsonc/version' '2.0'

# Byte-fidelity round-trip (diagnostic)
remoteclaw path emit ./AGENTS.md

More grammar examples:

# Quote keys containing / or .
remoteclaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias'

# Deep JSON/JSONC paths can use slash segments; they normalize to dotted subsegments
remoteclaw path set 'oc://remoteclaw.json/agents/list/0/tools/exec/security' 'allowlist' --dry-run

# Replace a JSONC leaf with a parsed object
remoteclaw path set 'oc://remoteclaw.json/gateway/auth/token' '{"source":"file","provider":"secrets","id":"/test"}' --value-json --dry-run

# Predicate search over JSONC children
remoteclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id'

# Insert into a JSONC array
remoteclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run

# Insert a JSONC object key
remoteclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run

# Append a JSONL event
remoteclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl

# Resolve the last JSONL value line
remoteclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl

# Resolve a YAML workflow step
remoteclaw path resolve 'oc://workflow.yaml/steps/0/id'

# Update a YAML scalar
remoteclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --dry-run

# Address markdown frontmatter
remoteclaw path resolve 'oc://AGENTS.md/[frontmatter]/name'

# Insert markdown frontmatter
remoteclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run

# Find markdown item fields
remoteclaw path find 'oc://SKILL.md/Tools/*/send_email'

# Validate a session-scoped path
remoteclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

Recipes by file kind

The same five verbs work across kinds; the addressing scheme dispatches on the file extension.

Markdown

frontmatter.md

---
name: drafter
description: email drafting agent
tier: core
---
## Tools
- gh: GitHub CLI
- curl: HTTP client
- send_email: enabled

$ remoteclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --human
leaf @ L4: "core" (string)

$ remoteclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --human
leaf @ L9: "GitHub CLI" (string)

$ remoteclaw path find 'oc://x.md/tools/*' --file frontmatter.md --human
3 matches for oc://x.md/tools/*:
  oc://x.md/tools/gh           →  node @ L9 [md-item]
  oc://x.md/tools/curl         →  node @ L10 [md-item]
  oc://x.md/tools/send-email   →  node @ L11 [md-item]

The [frontmatter] predicate addresses the YAML frontmatter block; tools matches the ## Tools heading via slug, and item leaves keep their slug form even when the source uses underscores (send_email becomes send-email).

JSONC

config.jsonc

{
  "plugins": {
    "github": {"enabled": true, "role": "vcs"},
    "slack":  {"enabled": false, "role": "chat"}
  }
}

$ remoteclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --file config.jsonc --human
leaf @ L4: "true" (boolean)

$ remoteclaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run
--dry-run: would write 142 bytes to /…/config.jsonc
{
  "plugins": {
    "github": {"enabled": true, "role": "vcs"},
    "slack":  {"enabled": true, "role": "chat"}
  }
}

JSONC edits go through jsonc-parser, so comments and whitespace survive a set. Run with --dry-run first to inspect the bytes before committing. .json files use the same adapter and edit path as .jsonc.

JSONL

{"event":"start","userId":"u1","ts":1}
{"event":"action","userId":"u1","ts":2}
{"event":"end","userId":"u1","ts":3}

$ remoteclaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human
1 match for oc://session.jsonl/[event=action]/userId:
  oc://session.jsonl/L2/userId  →  leaf @ L2: "u1" (string)

$ remoteclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --human
leaf @ L2: "2" (number)

Each line is a record. Address by predicate ([event=action]) when you do not know the line number, or by the canonical LN segment when you do. .ndjson files use the same adapter as .jsonl.

YAML

workflow.yaml

name: inbox-triage
steps:
  - id: fetch
    command: gmail.search
  - id: classify
    command: remoteclaw.invoke

$ remoteclaw path resolve 'oc://workflow.yaml/steps/0/id' --file workflow.yaml --human
leaf @ L3: "fetch" (string)

$ remoteclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --file workflow.yaml --dry-run
--dry-run: would write 99 bytes to /…/workflow.yaml
name: inbox-triage
steps:
  - id: fetch
    command: gmail.search
  - id: classify-renamed
    command: remoteclaw.invoke

YAML uses the yaml package’s Document API rather than a hand-rolled parser, so ordinary parse/emit round-trips preserve comments and authoring shape while resolved paths use the same map-key / sequence-index model as JSONC. The same adapter handles .yaml, .yml, and .lobster files.

Subcommand reference

resolve <oc-path>

Read a single leaf or node. Wildcards are rejected — use find for those. Exits 0 on a match, 1 on a clean miss, 2 on a parse error or refused pattern.

remoteclaw path resolve 'oc://AGENTS.md/tools/gh/risk' --human
remoteclaw path resolve 'oc://gateway.jsonc/server/port' --json

find <pattern>

Enumerate every match for a wildcard / predicate / union pattern. Exits 0 on at least one match, 1 on zero. File-slot wildcards are rejected with OC_PATH_FILE_WILDCARD_UNSUPPORTED — pass a concrete file (multi-file globbing is a follow-up feature).

remoteclaw path find 'oc://AGENTS.md/tools/**/risk'
remoteclaw path find 'oc://session.jsonl/[event=action]/userId'
remoteclaw path find 'oc://config.jsonc/plugins/{github,slack}/enabled'

set <oc-path> <value>

Write a leaf. Pair with --dry-run to preview the bytes that would be written without touching the file. Add --diff for a unified diff preview. Exits 0 on a successful write, 1 if the substrate refuses (for example, a sentinel guard hit), 2 on parse errors.

remoteclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run
remoteclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run --diff
remoteclaw path set 'oc://gateway.jsonc/version' '2.0'
remoteclaw path set 'oc://AGENTS.md/Tools/+gh/risk' 'low'

The +key insertion marker creates the named child if it does not already exist; +nnn and bare + work for indexed and append insertion respectively.

validate <oc-path>

Parse-only check. No filesystem access. Useful when you want to confirm a template path is well-formed before substituting variables, or when you want the structural breakdown for debugging:

$ remoteclaw path validate 'oc://AGENTS.md/tools/gh' --human
valid: oc://AGENTS.md/tools/gh
  file:    AGENTS.md
  section: tools
  item:    gh

Exits 0 when valid, 1 when invalid (with a structured code and message), 2 on argument errors.

emit <file>

Round-trip a file through the per-kind parser and emitter. The output should be byte-identical to the input on a sound file; divergence indicates a parser bug or a sentinel hit. Useful for debugging substrate behavior on real-world inputs.

remoteclaw path emit ./AGENTS.md
remoteclaw path emit ./gateway.jsonc --json

Exit codes

Code	Meaning
0	Success. (resolve / find: at least one match. set: write succeeded.)
1	No match, or set rejected by the substrate (no system-level error).
2	Argument or parse error.

Output mode

remoteclaw path is TTY-aware: human-readable output on a terminal, JSON when stdout is piped or redirected. --json and --human override the auto-detection.

Notes

• set writes bytes through the substrate’s emit path, which applies the redaction-sentinel guard automatically. A leaf carrying __REMOTECLAW_REDACTED__ (verbatim or as a substring) is refused at write time.
• JSONC parsing and leaf edits use the plugin-local jsonc-parser dependency, so comments and formatting are preserved on ordinary leaf writes instead of going through a hand-rolled parser/re-render path.
• path is not aware of last-known-good (LKG) config tracking or recovery; that lifecycle is owned elsewhere. If a file you edit through path is also LKG-tracked, the next config read decides whether to promote or recover it; treat a path edit the same as any other direct write to that file.

Related

• CLI reference