# Command Synchronous request/response handlers with typed schemas, validation, and a strict execution pipeline. --- Canonical: /handbook/blocks/command-pattern/ Source: web/src/content/handbook-cards/blocks/command-pattern.mdx Format: Markdown for agents --- A **command** is the foundational building block of PURISTA. It is a synchronous request-response function inside a service that receives a request, performs work, and returns a result. Commands are how you expose business logic to the outside world — whether through HTTP, cross-service calls, or programmatic APIs. Commands live inside services. A service groups related commands (and [subscriptions](/handbook/blocks/subscription-pattern/) and [streams](/handbook/blocks/stream-pattern/)) around a single domain boundary like "User Management" or "Billing." The service builder collects command definitions, and the event bridge routes incoming requests to the right handler.
Request/response semantics

A command always returns a result or an error. If you need fire-and-forget behavior, use a subscription instead. If you need continuous data flow, use a stream. If you need background work with retries, use a queue.

## In this section
What is a Command?
Understand the command lifecycle, context, and when to use commands.
The Command Builder
Define schemas, transforms, guards, events, and the business function with full type inference.
Cross-Service Calls
Call commands across services through the event bridge with full type safety.
HTTP Exposure
Expose commands as REST endpoints with path parameters, query strings, and OpenAPI docs.
Testing
Unit test handlers in isolation or validate the full runtime path with typed mocks.
## Quick reference ### Command lifecycle ```mermaid flowchart LR A[Incoming Request] --> B[Input Transform] B --> C[Payload & Parameter Validation] C --> D[Before Guards] D --> E[Command Function] E --> F[Output Validation] F --> G[After Guards] G --> H[Output Transform] H --> I[Response] C -.->|Invalid| J[Bad Request] D -.->|Denied| K[Unauthorized] E -.->|Error| L[Handled or Unhandled] F -.->|Invalid| M[Internal Error] ``` ### Key principles - Commands are **request/response** — they always return a result or error. - Schemas drive **TypeScript inference** throughout the pipeline. - Use **`async function`**, not arrow functions, to preserve `this` context. - Keep **auth logic in guards**, not inside the command function. - Choose the right handler: commands for sync work, [queues](/handbook/blocks/queue-pattern/) for background work, [subscriptions](/handbook/blocks/subscription-pattern/) for events, [streams](/handbook/blocks/stream-pattern/) for data flow.