Complete PyLD CLI transformations

CHANGELOG.md

@@ -12,9 +12,10 @@
   `identifierIssuer` option with an `IdentifierIssuer` instance for blank node
   identifiers. Defaults to `IdentifierIssuer('_:b')`, which preserves the
   previous behaviour.
-- `pyld` command-line tool (`get`, `expand`, `cache clear`), installed via
-  `pip install "PyLD[cli]"`, with remote contexts cached in a CLI-specific
-  SQLite file (overridable via `--cache-file` / `PYLD_CACHE_FILE`).
+- `pyld` command-line tool (`get`, `expand`, `compact`, `flatten`, `frame`,
+  `to-rdf`, `from-rdf`, and `cache clear`), installed via
+  `pip install "PyLD[cli]"`. Remote contexts are cached in a CLI-specific SQLite
+  file (overridable via `--cache-file` / `PYLD_CACHE_FILE`).
 
 ## 3.2.0 - 2026-08-17
 

Makefile

@@ -25,7 +25,7 @@ upgrade-submodules:
 download-bundled-contexts:
 	python scripts/download_contexts.py
 
-RUFF_TARGET = lib/pyld/*.py tests/*.py docs_macros.py
+RUFF_TARGET = lib/pyld/*.py lib/pyld/cli/*.py lib/pyld/cli/commands/*.py tests/*.py docs_macros.py
 
 lint:
 	ruff check $(RUFF_TARGET)

README.md

@@ -61,15 +61,20 @@ or define the requirement as `PyLD[requests]` or `PyLD[aiohttp]`.
 
 ## Command line
 
-Install the optional CLI extra to get a `pyld` console script:
+Install the optional CLI extra to get a JSON-LD 1.1 `pyld` console script:
 
 ```bash
 pip install "PyLD[cli]"
 pyld expand document.jsonld
-pyld expand https://example.com/doc.jsonld
+pyld compact document.jsonld context.jsonld
+pyld frame document.jsonld frame.jsonld
+pyld to-rdf document.jsonld
+pyld from-rdf document.nq
 ```
 
-See the [CLI documentation](https://digitalbazaar.github.io/pyld/cli/).
+The CLI also provides `get`, `flatten`, and HTTP cache management. See the
+[CLI documentation](https://digitalbazaar.github.io/pyld/cli/) for all commands,
+options, and stdin support.
 
 ## Usage
 

docs/cli/.pages

@@ -2,4 +2,9 @@ nav:
   - index.md
   - get.md
   - expand.md
+  - compact.md
+  - flatten.md
+  - frame.md
+  - to-rdf.md
+  - from-rdf.md
   - cache.md

docs/cli/compact.md

@@ -0,0 +1,32 @@
+---
+hide: [toc]
+---
+
+# :material-arrow-collapse: `pyld compact`
+
+!!! warning "Requires `pip install PyLD[cli]`"
+
+Compact a JSON-LD document using a required context. `INPUT` accepts a path,
+URL, or `-`; `CONTEXT` accepts a path, URL, or `-`. Only one operand may read
+from standard input.
+
+::: mkdocs-typer2
+    :module: pyld.cli
+    :name: pyld
+    :command: compact
+    :termynal: true
+    :width: 88
+
+## Example
+
+=== "Example"
+
+    {{ terminal('pyld compact docs/examples/data/person.jsonld docs/examples/data/context.jsonld', indent=4) }}
+
+=== "person.jsonld"
+
+    {{ example_data('data/person.jsonld', indent=4) }}
+
+=== "context.jsonld"
+
+    {{ example_data('data/context.jsonld', indent=4) }}

docs/cli/flatten.md

@@ -0,0 +1,26 @@
+---
+hide: [toc]
+---
+
+# :material-format-list-group: `pyld flatten`
+
+!!! warning "Requires `pip install PyLD[cli]`"
+
+Flatten a JSON-LD document. Add `--context` to compact the flattened output.
+
+::: mkdocs-typer2
+    :module: pyld.cli
+    :name: pyld
+    :command: flatten
+    :termynal: true
+    :width: 88
+
+## Example
+
+=== "Example"
+
+    {{ terminal('pyld flatten docs/examples/data/person.jsonld', indent=4) }}
+
+=== "person.jsonld"
+
+    {{ example_data('data/person.jsonld', indent=4) }}

docs/cli/frame.md

@@ -0,0 +1,32 @@
+---
+hide: [toc]
+---
+
+# :material-image-frame: `pyld frame`
+
+!!! warning "Requires `pip install PyLD[cli]`"
+
+Frame a JSON-LD document using a required frame. `INPUT` accepts a path, URL,
+or `-`; `FRAME` accepts a path, URL, or `-`. Only one operand may read from
+standard input.
+
+::: mkdocs-typer2
+    :module: pyld.cli
+    :name: pyld
+    :command: frame
+    :termynal: true
+    :width: 88
+
+## Example
+
+=== "Example"
+
+    {{ terminal('pyld frame docs/examples/data/person.jsonld docs/examples/data/frame.jsonld', indent=4) }}
+
+=== "person.jsonld"
+
+    {{ example_data('data/person.jsonld', indent=4) }}
+
+=== "frame.jsonld"
+
+    {{ example_data('data/frame.jsonld', indent=4) }}

docs/cli/from-rdf.md

@@ -0,0 +1,27 @@
+---
+hide: [toc]
+---
+
+# :material-import: `pyld from-rdf`
+
+!!! warning "Requires `pip install PyLD[cli]`"
+
+Convert raw N-Quads from a local path or `-` into JSON-LD. Remote RDF input is
+not supported.
+
+::: mkdocs-typer2
+    :module: pyld.cli
+    :name: pyld
+    :command: from-rdf
+    :termynal: true
+    :width: 88
+
+## Example
+
+=== "Example"
+
+    {{ terminal('pyld from-rdf docs/examples/data/person.nq', indent=4) }}
+
+=== "person.nq"
+
+    {{ example_data('data/person.nq', indent=4) }}

docs/cli/index.md

@@ -7,7 +7,13 @@ icon: material/console
 
 !!! warning "Requires `pip install PyLD[cli]`"
 
-PyLD ships a `pyld` command-line tool for JSON-LD transformations.
+PyLD ships a `pyld` command-line tool for JSON-LD 1.1 transformations.
+
+JSON-LD inputs accept a local path, URL, or explicit `-` for standard input.
+Contexts and frames accept a local path, URL, or `-`. Only one operand in an
+invocation may consume standard input. Raw N-Quads input accepts only a local
+path or `-`, and N-Quads output is written directly to standard output without
+JSON quoting or terminal styling.
 
 <div class="grid cards" markdown>
 
@@ -23,6 +29,36 @@ PyLD ships a `pyld` command-line tool for JSON-LD transformations.
 
     Expand a JSON-LD document into full IRI-based form.
 
+-   [:material-arrow-collapse:{ .lg .middle } `pyld compact`](compact.md)
+
+    ---
+
+    Compact a JSON-LD document using a context.
+
+-   [:material-format-list-group:{ .lg .middle } `pyld flatten`](flatten.md)
+
+    ---
+
+    Flatten a JSON-LD document into a single node map.
+
+-   [:material-image-frame:{ .lg .middle } `pyld frame`](frame.md)
+
+    ---
+
+    Frame a JSON-LD document into a selected tree shape.
+
+-   [:material-export:{ .lg .middle } `pyld to-rdf`](to-rdf.md)
+
+    ---
+
+    Convert JSON-LD to raw N-Quads.
+
+-   [:material-import:{ .lg .middle } `pyld from-rdf`](from-rdf.md)
+
+    ---
+
+    Convert raw N-Quads to JSON-LD.
+
 -   [:material-cached:{ .lg .middle } `pyld cache`](cache.md)
 
     ---

docs/cli/to-rdf.md

@@ -0,0 +1,26 @@
+---
+hide: [toc]
+---
+
+# :material-export: `pyld to-rdf`
+
+!!! warning "Requires `pip install PyLD[cli]`"
+
+Convert JSON-LD to raw N-Quads. `INPUT` accepts a path, URL, or `-`.
+
+::: mkdocs-typer2
+    :module: pyld.cli
+    :name: pyld
+    :command: to-rdf
+    :termynal: true
+    :width: 88
+
+## Example
+
+=== "Example"
+
+    {{ terminal('pyld to-rdf docs/examples/data/person.jsonld', indent=4) }}
+
+=== "person.jsonld"
+
+    {{ example_data('data/person.jsonld', indent=4) }}

docs/examples/data/context.jsonld

@@ -0,0 +1,5 @@
+{
+  "@context": {
+    "name": "http://schema.org/name"
+  }
+}

docs/examples/data/frame.jsonld

@@ -0,0 +1,5 @@
+{
+  "@context": {
+    "name": "http://schema.org/name"
+  }
+}

docs/examples/data/person.nq

@@ -0,0 +1 @@
+<http://example.com/ada> <http://schema.org/name> "Ada Lovelace" .