document Bicep CLI jsonrpc

Author: mumian

articles/azure-resource-manager/bicep/bicep-cli.md

@@ -3,7 +3,7 @@ title: Bicep CLI commands and overview
 description: Describes the commands that you can use in the Bicep CLI. These commands include building Azure Resource Manager templates from Bicep.
 ms.topic: reference
 ms.custom: devx-track-azurecli, devx-track-bicep, devx-track-arm-template
-ms.date: 10/23/2024
+ms.date: 10/30/2024
 ---
 
 # Bicep CLI commands
@@ -140,6 +140,99 @@ To install a specific version:
 az bicep install --version v0.3.255
 ```
 
+## jsonrpc
+
+The `jsonrpc` command enables running the Bicep CLI with a JSON-RPC interface, allowing for programmatic interaction with structured output and avoiding cold-start delays when compiling multiple files. This setup also supports building libraries to interact with Bicep files programmatically in non-.NET languages.
+
+The wire format for sending and receiving input/output is header-delimited, using the following structure, where `\r` and `\n` represent carriage return and line feed characters:
+
+```
+Content-Length: <length>\r\n\r\n<message>\r\n\r\n
+```
+
+* `<length>` is the length of the `<message>` string, including the trailing `\r\n\r\n`.
+* `<message>` is the raw JSON message.
+
+For example:
+
+```
+Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n
+```
+
+The following message shows an example for Bicep version.
+
+* The input:
+
+  ```json
+  {
+    "jsonrpc": "2.0",
+    "id": 0,
+    "method": "bicep/version",
+    "params": {}
+  }
+  ```
+  
+* The output:
+
+  ```json
+  {
+    "jsonrpc": "2.0",
+    "id": 0,
+    "result": {
+      "version": "0.24.211"
+    }
+  }
+  ```
+
+For the available methods & request/response bodies, see [`ICliJsonRpcProtocol.cs`](../../src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs).
+For an example establinging a JSONRPC connection and interacting with Bicep files programmatically using Node, see [`jsonrpc.test.ts`](../../src/Bicep.Cli.E2eTests/src/jsonrpc.test.ts).
+
+### Usage for named pipe
+
+Use the following syntax to connect to an existing named pipe as a JSONRPC client.
+
+```bicep cli
+bicep jsonrpc --pipe <named_pipe>`
+```
+
+`<named_pipe>` is an existing named pipe to connect the JSONRPC client to.
+
+To connect to a named pipe (OSX/Linux) :
+
+```bicep cli
+bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock
+```
+
+To connect to a named pipe (Windows) :
+
+```bicep cli
+bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`
+```
+
+For more examples, see [C#](https://github.com/Azure/bicep/blob/096c32f9d5c42bfb85dff550f72f3fe16f8142c7/src/Bicep.Cli.IntegrationTests/JsonRpcCommandTests.cs#L24-L50) and [node.js](https://github.com/anthony-c-martin/bicep-node/blob/4769e402f2d2c1da8d27df86cb3d62677e7a7456/src/utils/jsonrpc.ts#L117-L151).
+
+### Usage for TCP socket
+
+Use the following syntax to connect to an existing TCP socket as a JSONRPC client.
+
+```bicep cli
+bicep jsonrpc --socket <tcp_socket>
+```
+
+`<tcp_socket>` is a a socket number to connect the JSONRPC client to.
+
+To connect to a TCP socket
+
+`bicep jsonrpc --socket 12345`
+
+### Usage for stdin and stdout
+
+Use the following syntax to run the JSONRPC interface using stdin & stdout for messages.
+
+```bicep cli
+bicep jsonrpc --stdio
+```
+
 ## lint
 
 The `lint` command returns the errors and the [linter rule](./linter.md) violations of a Bicep file.
@@ -264,19 +357,19 @@ module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
 
 The local cache is found in:
 
-- On Windows
+* On Windows
 
     ```path
     %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>
     ```
 
-- On Linux
+* On Linux
 
     ```path
     /home/<username>/.bicep
     ```
 
-- On Mac
+* On Mac
 
     ```path
     ~/.bicep
@@ -318,6 +411,6 @@ If the Bicep CLI hasn't been installed, you'll encounter an error message statin
 
 To learn about deploying a Bicep file, see:
 
-- [Azure CLI](deploy-cli.md)
-- [Cloud Shell](deploy-cloud-shell.md)
-- [PowerShell](deploy-powershell.md)
+* [Azure CLI](deploy-cli.md)
+* [Cloud Shell](deploy-cloud-shell.md)
+* [PowerShell](deploy-powershell.md)