Structure of an OIP Directory Row for CLI Objects

OIP Directory Row Definition

An 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.

Directory Row Properties

An OIP Directory Row object possesses the following properties:

key: A unique string identifier for the work object. This key is used in /api/dispatch invocations. type: A string indicating the object's category, set to "cli" for CLI command definitions. command: A string representing the base command executable or script name. description: A human-readable string explaining the object's purpose and functionality. 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). 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). output_format: A string indicating the expected format of the command's output, such as "json" or "text". invocation_method: A string specifying how the command is executed, such as "exec" for direct execution or "shell" for shell interpretation. source_url: A URL (Uniform Resource Locator) string pointing to the source code or executable location of the CLI command. schema: An optional JSON Schema object that provides additional validation rules for the combined input (arguments and flags).

Route for Directory Row Creation and Update

An 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.

curl -X POST https://miscsubjects.com/api/dispatch \
  -H "Content-Type: application/json" \
  -d '{
    "key": "my-cli-tool-v1",
    "body": {
      "type": "directory_row",
      "command": "mytool",
      "description": "A sample CLI tool for processing files.",
      "args": [
        {
          "name": "input_file",
          "type": "string",
          "description": "Path to the input file.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "output",
          "type": "string",
          "description": "Path for the output file.",
          "required": false,
          "default": "./output.txt",
          "short_alias": "-o"
        },
        {
          "name": "verbose",
          "type": "boolean",
          "description": "Enable verbose logging.",
          "required": false,
          "default": false,
          "short_alias": "-v"
        }
      ],
      "output_format": "text",
      "invocation_method": "exec",
      "source_url": "https://github.com/example/mytool/releases/v1.0.0"
    }
  }'

Receipt for Directory Row Operation

The 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.

{
  "inv_ID": "inv_01HXXXXXXX",
  "status": "success",
  "message": "Object dispatched to ledger.",
  "object_key": "my-cli-tool-v1",
  "timestamp": "2023-10-27T10:00:00Z"
}

Ledger Record of Directory Rows

Every 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.

End-to-End Example: Defining a CLI Tool

This 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.

1. Object Definition: The JSON body in the curl command above defines the my-cli-tool-v1 work object.
2. Invoke: The curl command POSTs this object to /api/dispatch.
3. Ledger: The OIP system appends this object definition to its ledger.
4. Receipt: The system returns a receipt with an inv_ID like inv_01HXXXXXXX.
5. Replay: A conformant client can retrieve this definition from the ledger using the inv_ID or by querying for my-cli-tool-v1.
6. 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.

Receipt Rule for Directory Row

A 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.

Conformance Rule for Directory Row Interpretation

A 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.

OIP Directory Row and MCP (Model Context Protocol)

An 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.