Direct API Access and Generic Commands

The primitive CLI exposes every operation in the operation manifest as a generic command, in addition to the task-oriented commands (primitive send, primitive functions deploy, and so on) documented elsewhere. Use the generic form when a task-oriented command doesn't exist yet, or when you need full schema parity with the underlying OpenAPI operation.

Generic operation commands#

Every generated operation is callable directly as tag:command, where the command name is the kebab-cased operation id from the manifest:

primitive emails:list-emails
primitive sending:reply-to-email

Reach for the task-oriented commands (primitive send, primitive reply, primitive memories, primitive routes) for normal workflows. The generic tag:operation-id form stays available for compatibility and full schema parity, and exposes every field the OpenAPI schema declares rather than a curated subset:

primitive send --to alice@example.com --body "Hello"

Listing every operation#

primitive list-operations prints the full operation manifest as JSON: every operation's command name, HTTP method, path, parameters, and inlined request/response JSON Schemas.

primitive list-operations

Pipe it through jq to inspect a single operation's shape without probing the server with malformed payloads:

primitive list-operations | jq '.[] | select(.command == "send-email")'
primitive list-operations | jq '.[] | select(.command == "send-email") | .requestSchema'

This is the same manifest data the CLI's generic api-command path and describe helper read from; list-operations is the raw dump for scripting and agent tooling.

Describing an operation#

primitive describe prints one operation's manifest entry, by command name: method, path, parameters, and the inlined request/response schemas. Use it instead of list-operations | jq when you already know which operation you want:

primitive describe send-email

The response schema is derived from the operation's 200/201 envelope with the data field peeled off, so what's printed is the shape you actually get back, not the full { success, data, meta } envelope.

api-client plumbing#

Every command, generic or task-oriented, builds its request client with createAuthenticatedCliApiClient, a wrapper over the shared PrimitiveApiClient from @primitivedotdev/api-core. It resolves the API key (the --api-key flag, PRIMITIVE_API_KEY, or saved OAuth login credentials) and the base URL, then hands back an authenticated client that each command passes to a specific generated operation function.

Errors from any generated operation call go through a shared error-payload extractor (extractErrorPayload) and a shared printer (writeErrorWithHints), so the error code, message, gates, and request id read the same whether you called a task-oriented command or a bare tag:operation-id command. A 401 additionally triggers an unauthorized hint pointing at re-authentication.

Shell completion and endpoint test redirects#

Bash/zsh/powershell/fish completion setup and the internal endpoints-test-redirect helper (exercised by primitive routes-test and primitive functions-test-function) are covered on Shell Completion and Endpoint Test Redirects.

Next steps#