{"slug":"oip-directory-row-structure","title":"Structure of an OIP Directory Row for CLI Objects","body":"An OIP (Object Invocation Protocol) Directory Row defines the structure and invocation parameters for a specific work object, enabling its discovery and execution. Each row specifies a unique key, a type, and detailed command-line interface (CLI) arguments and flags. The OIP ledger records all directory row creations and updates, providing an immutable history of object definitions. Conformant systems interpret these rows to construct and execute CLI commands.\n\n## OIP Directory Row Definition\n\nAn OIP Directory Row is a JSON (JavaScript Object Notation) object that specifies the metadata and invocation shape for a work object, particularly for CLI commands. It provides a machine-readable schema for constructing and validating command invocations. The OIP unit is the work object, and a directory row defines one such object.\n\n### Directory Row Properties\n\nAn OIP Directory Row object possesses the following properties:\n\n*   `key`: A unique string identifier for the work object. This key is used in `/api/dispatch` invocations.\n*   `type`: A string indicating the object's category, set to `\"cli\"` for CLI command definitions.\n*   `command`: A string representing the base command executable or script name.\n*   `description`: A human-readable string explaining the object's purpose and functionality.\n*   `args`: An array of JSON objects, each defining a positional argument for the command. Each argument object specifies `name` (string), `type` (string, e.g., `\"string\"`, `\"integer\"`, `\"boolean\"`), `description` (string), `required` (boolean), and `default` (any type, optional).\n*   `flags`: An array of JSON objects, each defining a named flag or option for the command. Each flag object specifies `name` (string), `type` (string), `description` (string), `required` (boolean), `default` (any type, optional), and `short_alias` (string, optional, e.g., `\"-v\"` for `--verbose`).\n*   `output_format`: A string indicating the expected format of the command's output, such as `\"json\"` or `\"text\"`.\n*   `invocation_method`: A string specifying how the command is executed, such as `\"exec\"` for direct execution or `\"shell\"` for shell interpretation.\n*   `source_url`: A URL (Uniform Resource Locator) string pointing to the source code or executable location of the CLI command.\n*   `schema`: An optional JSON Schema object that provides additional validation rules for the combined input (arguments and flags).\n\n## Route for Directory Row Creation and Update\n\nAn OIP Directory Row is created or updated by invoking the `/api/dispatch` route with a work object whose `type` is `\"directory_row\"`. The invocation appends the object definition to the OIP ledger.\n\n```bash\ncurl -X POST https://miscsubjects.com/api/dispatch \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"key\": \"my-cli-tool-v1\",\n    \"body\": {\n      \"type\": \"directory_row\",\n      \"command\": \"mytool\",\n      \"description\": \"A sample CLI tool for processing files.\",\n      \"args\": [\n        {\n          \"name\": \"input_file\",\n          \"type\": \"string\",\n          \"description\": \"Path to the input file.\",\n          \"required\": true\n        }\n      ],\n      \"flags\": [\n        {\n          \"name\": \"output\",\n          \"type\": \"string\",\n          \"description\": \"Path for the output file.\",\n          \"required\": false,\n          \"default\": \"./output.txt\",\n          \"short_alias\": \"-o\"\n        },\n        {\n          \"name\": \"verbose\",\n          \"type\": \"boolean\",\n          \"description\": \"Enable verbose logging.\",\n          \"required\": false,\n          \"default\": false,\n          \"short_alias\": \"-v\"\n        }\n      ],\n      \"output_format\": \"text\",\n      \"invocation_method\": \"exec\",\n      \"source_url\": \"https://github.com/example/mytool/releases/v1.0.0\"\n    }\n  }'\n```\n\n## Receipt for Directory Row Operation\n\nThe OIP proof for a directory row creation or update is the receipt returned by the `/api/dispatch` route. This receipt confirms the successful recording of the directory row definition in the OIP ledger. The receipt contains an `inv_ID` (invocation ID) that uniquely identifies the ledger entry.\n\n```json\n{\n  \"inv_ID\": \"inv_01HXXXXXXX\",\n  \"status\": \"success\",\n  \"message\": \"Object dispatched to ledger.\",\n  \"object_key\": \"my-cli-tool-v1\",\n  \"timestamp\": \"2023-10-27T10:00:00Z\"\n}\n```\n\n## Ledger Record of Directory Rows\n\nEvery OIP Directory Row definition, upon successful invocation, is appended as an immutable record to the OIP ledger. The ledger entry for a directory row includes the `key`, the `body` containing the full directory row structure, and metadata such as the invocation timestamp and source. This record is retrievable via the `inv_ID` at `/api/dispatch?receipt=inv_ID`.\n\n## End-to-End Example: Defining a CLI Tool\n\nThis example demonstrates the creation of a directory row for a CLI tool named `mytool` that processes an input file and optionally writes to an output file with verbose logging. The OIP loop is object, invoke, ledger, receipt, replay, repair.\n\n1.  **Object Definition**: The JSON body in the `curl` command above defines the `my-cli-tool-v1` work object.\n2.  **Invoke**: The `curl` command `POST`s this object to `/api/dispatch`.\n3.  **Ledger**: The OIP system appends this object definition to its ledger.\n4.  **Receipt**: The system returns a receipt with an `inv_ID` like `inv_01HXXXXXXX`.\n5.  **Replay**: A conformant client can retrieve this definition from the ledger using the `inv_ID` or by querying for `my-cli-tool-v1`.\n6.  **Repair**: If the definition is incorrect, a new directory row with the same `key` but updated `body` can be dispatched, creating a new ledger entry and effectively updating the object's definition for future invocations.\n\n## Receipt Rule for Directory Row\n\nA valid OIP receipt for a directory row operation contains a `status` of `\"success\"`, an `inv_ID` string, and an `object_key` matching the `key` provided in the dispatched object's `body`.\n\n## Conformance Rule for Directory Row Interpretation\n\nA system conforms to the OIP Directory Row specification if it can parse a `directory_row` object, correctly identify its `command`, `args`, and `flags`, and construct a valid CLI command string based on provided invocation parameters. For example, given the `my-cli-tool-v1` directory row and input `{\"input_file\": \"data.txt\", \"output\": \"result.txt\", \"verbose\": true}`, a conformant system constructs the command `mytool data.txt -o result.txt -v`.\n\n## OIP Directory Row and MCP (Model Context Protocol)\n\nAn OIP Directory Row defines the specific structure and invocation parameters for a single CLI work object, enabling direct, programmatic execution. It specifies the command's shape and expected inputs and outputs. The OIP Directory Row is a discrete, self-contained definition for a command. In contrast, MCP (Model Context Protocol) defines a broader interaction context where a model connects to a server that exposes tools, resources, and prompts over a session. An MCP session orchestrates a sequence of interactions and tool uses, potentially leveraging multiple OIP-defined tools. An OIP Directory Row provides the granular definition of a tool's interface, while MCP provides the framework for a model to discover and utilize such tools within a conversational or task-oriented session. An OIP Directory Row specifies a single command's interface; an MCP session defines a dynamic environment for tool interaction.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","dynamic"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"prov":{"model":"system/oip_articles","action":"generate"}}