{"slug":"oip-cli","title":"What is a CLI?","body":"## What this article explains\n\nA CLI is a command line interface. It is a way to operate software by typing commands in a terminal.\n\n## Plain words\n\nA browser button is one interface. A terminal command is another interface. A CLI command has a program name, flags, arguments, a working directory, output, and an exit status.\n\n## How CLIs work in OIP\n\nOIP stands for Object Invocation Protocol. It is a way to make software objects callable using standard web addresses, called URLs. A URL is a web address that points to a resource on the internet.\n\nThe miscsubjects.com build exposes CLI work as objects. This happens when a directory row points to a shell, model CLI, deployment command, or local bridge command. The row must explain the exact command shape and where proof appears.\n\n## OIP and Model Context Protocol (MCP)\n\nMCP stands for Model Context Protocol. It is an open standard.\n\nIn MCP, an AI model connects to an MCP server over a session. A server is a computer program or device that provides a service to other computer programs or devices, called clients. A session is a temporary, interactive information exchange between two or more communicating devices.\n\nThe MCP server exposes tools, resources, and prompts that the model can call. MCP is NOT a content-management system.\n\nOIP differs from MCP. OIP uses plain URLs and receipts. A receipt is a record of an action or transaction. OIP does not use a persistent session. Any model that can open a URL can act using OIP.\n\n## Machine shape\n\nA CLI object is machine-native when it includes `command`, `args`, `cwd`, `env_requirements`, `stdout`, `stderr`, `exit_status`, `ledger`, and `repair`.\n\n## Operating OIP CLI Objects with curl\n\nThe miscsubjects.com build allows you to invoke OIP objects using simple web requests. You can use the `curl` command-line tool to make these requests.\n\nTo invoke an object, you send a request to the `/api/dispatch` endpoint. An endpoint is a specific URL where an API can be accessed by a client. API stands for Application Programming Interface. It is a set of rules that allows different software applications to communicate with each other.\n\n### Invoking with GET\n\nTo invoke an object using a GET request, include the object's `key` and any `body` data as URL parameters.\n\nExample: Invoke an object named `my-cli-object` with a simple body.\n\n```bash\ncurl \"https://miscsubjects.com/api/dispatch?invoke=my-cli-object&body=hello%20world\"\n```\n\n### Invoking with POST\n\nTo invoke an object using a POST request, send the `key` and `body` in the request's JSON payload. JSON stands for JavaScript Object Notation. It is a lightweight data-interchange format.\n\nExample: Invoke an object named `another-cli-object` with a JSON body.\n\n```bash\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"key\": \"another-cli-object\", \"body\": {\"message\": \"hello from post\"}}' \\\n  https://miscsubjects.com/api/dispatch\n```\n\n### Checking the receipt\n\nEvery invocation lands in an append-only ledger. You get a receipt for each invocation.\n\nTo check the status or result of an invocation, use the `receipt` parameter with the invocation ID.\n\nExample: Check receipt for invocation ID `inv_12345`.\n\n```bash\ncurl \"https://miscsubjects.com/api/dispatch?receipt=inv_12345\"\n```\n## Latest clarity reviews (live)\n\nFresh models are sent this article's bundle and asked two separate questions: how clear is the machine JSON, and how clear is the English body. Scores are 0 to 10. The full history is in the append-only ledger.\n\n- 2026-07-03 03:10 · model `gemini/gemini-2.5-flash` · NEEDS WORK · JSON 9/10 · English 7/10 · zero-context human 6/10\n  - gaps named: directory row structure; scoped capability tokens; invocation ID generation\n- 2026-07-02 23:43 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10\n  - gaps named: MCP explanation; Detailed curl usage examples\n\nHow the loop self-corrects: a failing review queues a model revision of this article (a new append-only version). A missing concept named by a reviewer queues a brand-new machine-written article, which then enters the same review cycle.","hero":null,"images":[],"style":{"accent":"#16324f","measure":860},"tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"model":null,"ledger":null,"embeds":[],"widgets":[{"type":"stat","value":1,"label":"revision"},{"type":"note","title":"Zero-context rule","text":"A reader should understand the protocol unit, object contract, invocation route, receipt schema, and repair path from this page plus its machine bundle."},{"type":"note","title":"Machine-native rule","text":"The JSON is the executable map: object, routes, inputs, proof loop, ledger, and next article to open."}],"home":false,"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"}],"reviews":[],"extra":{"oip_virtual":true,"oip_type":"primer","count":1,"metric":"revision","primer":"oip-cli","version":1,"author_model":"gemini/gemini-2.5-flash","revision_source":"revision"},"register":"oip_protocol","status":"published","revisions":0,"contributions":[],"provenance":[{"action":"generate","model":"system/oip_articles","ts":"2026-07-03T00:21:34-07:00","hash":"virtual-oip","tokens_in":0,"tokens_out":0}],"energy":{"passes":1,"tokens_in":0,"tokens_out":0,"tokens_total":0,"cost_usd":0,"models":{"system/oip_articles":1},"head":"virtual-oip"},"posted_at":"2026-07-02T00:00:00.000Z","created_at":"2026-07-02T00:00:00.000Z","updated_at":"2026-07-03T00:21:34-07:00"}