command
/command
Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "r
- Author
- proteanhq ↗
- Repository
- protean ↗
- Licence
- Apache-2.0
- Last repository change
- 11.11.2026
Assessment and security
- Files in this package
- 13
- Scripts
- 7
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 7 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: __init__.py, assets/__init__.py, assets/command_inheritance.py, assets/command_simple.py, assets/command_validation.py, assets/command_with_value_object.py, assets/submitting_commands.py
What it does and when to use it
Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "r
Triggers from the description
Original author description
Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "r
How it works
- Basic structure
- Key rules
- Fields and options
- Quick example
- Submitting commands
- Common mistakes
- Detailed references
- Verify your work
SKILL.md preview
---
name: command
description: Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "register a user", "cancel a reservation"). Commands can be processed synchronously or asynchronously.
license: Apache-2.0
compatibility: Requires Python 3.11+, protean framework
metadata:
author: proteanhq
version: "0.1"
category: element
diagnostic_codes:
- COMMAND_NOT_IMPERATIVE
- UNUSED_COMMAND
---
# Command
A command carries one request to change one aggregate, and exactly one command handler processes it. This skill defines commands: fields, naming, and how to submit them.
## Basic structure
A command is defined using the `@domain.command(part_of="...")` decorator:
```python
from protean import Domain
from protean.fields import String, Identifier
domain = Domain()
@domain.aggregate
class Order:
customer_id: String(required=True)
@domain.command(part_of="Order")
class PlaceOrder:
order_id: Identifier(required=True)
customer_id: String(required=True)
product_id: String(required=True)
```
## Key rules
1. **Commands must be associated with aggregates**: Always specify `part_of` parameter with the aggregate name
2. **Commands are named with imperative verbs**: Use imperative mood: `PlaceOrder`, not `OrderPlaced`
3. **Commands are immutable**: Once created, commands cannot be modified
4. **Commands are DTOs**: Can contain simple fields and value objects, but NOT entities or aggregates (no HasOne, HasMany)
5. **Commands are unique**: Each command is unique throughout the domain
6. **One handler per command**: A command can only be processed by one command handler
7. **Commands carry intent**: They describe what should happen, not what happened (that is events)
8. **Commands have metadata**: Protean automatically adds timestamps, unique IDs, and versioning
9. **Commands are submitted via `domain.process()`**: The domain dispatches to the appropriate handler
10. **Commands support sync and async processing**: Controlled per-instance or via domain configuration
## Fields and options
| Field/Option | Purpose | Required |
|--------------|---------|----------|
| `part_of` | Associate command with an aggregate | Yes (unless abstract) |
| `abstract` | Mark as abstract base command | No |
| `__version__` | Schema version as positive integer (defaults to `1`) | No |
### Supported field types
```python
from protean.fields import (
String, Integer, Float, Boolean,
DateTime, Date, Identifier,
List, Dict, ValueObject,
)
```
Commands cannot use `HasOne`, `HasMany`, or `Reference` fields.
## Quick example
```python
from protean import Domain, handle
from protean.fields import DateTime, Decimal, Identifier, String
domain = Domain()
@domain.aggregate
class Order:
order_id: Identifier(identifier=True)
customer_id: String(required=True)
total_amount: Decimal(precision=19, scale=4)
@domain.command(part_of="Order")
class PlaceOrder:
order_id: Identifier(required=True)
customer_id: String(required=True)
total_amount: Decimal(precision=19, scale=4, required=True)
# Register the handler before init(); one registered after is not wired
@domain.command_handler(part_of="Order")
class OrderCommandHandler:
@handle(PlaceOrder)
def place_order(self, command: PlaceOrder):
order = Order(
order_id=command.order_id,
customer_id=command.customer_id,
total_amount=command.total_amount,
)
domain.repository_for(Order).add(order)
domain.init(traverse=False)
# Create and submit command
with domain.domain_context():
command = PlaceOrder(
order_id="ORD-001",
customer_id="CUST-123",
total_amount=99.99
)
domain.process(command)
```
## Submitting commands
Commands are submitted to the domain for processing:
```python
with domain.domain_context():
# Default processing (based on domain config, default is async)
domain.process(command)
# Explicit synchronous processing
domain.process(command, asynchronous=False)
# Explicit asynchronous processing
domain.process(command, asynchronous=True)
```
Domain-wide configuration:
```python
# In domain.toml
# command_processing = "sync" # or "async"
# In code
domain.config["command_processing"] = "sync"
```
## Common mistakes
### Including entities in commands
```python
# fragment
@domain.command(part_of="Order")
class PlaceOrder:
items = HasMany(OrderItem) # Wrong! Commands can't contain entities
```
Instead: Only fields and value objects
```python
@domain.value_object
class Money:
amount: Decimal(precision=19, scale=4, required=True)
currency: String(max_length=3, default="USD")
@domain.command(part_of="Order")
class PlaceOrder:
order_id: Identifier(required=True)
customer_id: String(required=True)
items: List() # Serialize as list of dicts
total = ValueObject(Money) # Value objects are allowed
```
### Trying to modify a command after creation
```python
# fragment
command = PlaceOrder(order_id="ORD-001", customer_id="CUST-123")
command.customer_id = "CUST-456" # Raises IncorrectUsageError!
```
Instead: Create a new command instance with the values you need.
### What `check` reports
`check` inspects your commands and reports these diagnostics:
- `COMMAND_NOT_IMPERATIVE`: the command is named in a mood that is not imperative (`OrderPlacement`), so it reads like data or an event. Rename it to a verb-first imperative phrase (`PlaceOrder`). If the name already starts with a verb Protean does not know (`AdjustStock`), add the verb to `[lint].command_verbs` in `domain.toml` instead of renaming.
- `UNUSED_COMMAND`: the command has no registered handler, so nothing processes it. Add a command handler method for it, or remove the command if it is unused.
## Detailed references
### Core Concepts
- [Commands with Value Objects](references/with-value-objects.md): Using value objects in commands
- [Command Validation](references/command-validation.md): Field validation and error handling
- [Command Processing](references/command-processing.md): Synchronous and asynchronous processing
- [Command Inheritance](references/command-inheritance.md): Abstract commands and inheritance
- [Anti-patterns](references/anti-patterns.md): Common mistakes and how to avoid them
### Complete Examples
- [Simple Command](assets/command_simple.py): Basic commands with simple fields
- [Command with Value Objects](assets/command_with_value_object.py): Commands containing value objects
- [Command Validation](assets/command_validation.py): Field validation examples
- [Command Inheritance](assets/command_inheritance.py): Abstract base commands and inheritance
- [Submitting Commands](assets/submitting_commands.py): Command submission and processing
### Related Skills
- `aggregate`: Commands are always part of aggregates
- `command-handler`: How commands are processed
- `event`: Commands and events are complementary (commands = intent, events = result)
- `value-object`: Commands can contain value objects
- [CQRS](https://docs.proteanhq.com/concepts/architecture/cqrs/): Commands are the "C" in CQRS
## Verify your work
- [Verify with check](../../references/verify-with-check.md): run `check` and resolve what it reports
Files in this package (13)
- SKILL.md 8 KB
- __init__.py 1 KB
- assets/__init__.py 1 KB
- assets/command_inheritance.py 4 KB
- assets/command_simple.py 4 KB
- assets/command_validation.py 4 KB
- assets/command_with_value_object.py 5 KB
- assets/submitting_commands.py 4 KB
- references/anti-patterns.md 6 KB
- references/command-inheritance.md 3 KB
- references/command-processing.md 4 KB
- references/command-validation.md 4 KB
- references/with-value-objects.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · proteanhq/protean | 100 | Apache-2.0 |
| proteanhq/protean | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version d6ed13ac3e2f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100query
Define a Protean query, an immutable DTO representing a read intent against a projection (read model). Queries carry the parameters needed to fetch data on the read side of CQRS and are answered by query handlers via domain.dispatch(). Queries are associated with a projection… - 100command-handler
Define a Protean command handler, a class responsible for receiving domain commands and orchestrating state changes in aggregates. Command handlers extract data from commands, load or create aggregates, invoke aggregate methods, and persist state changes. They are always… - 100ddd-api-designer
API design from domain model — CQRS command/query separation, REST API endpoint design, data object conversion chain (PO→DO→DTO→VO), unified response format, OpenAPI/Swagger generation, BFF pattern, API versioning, and security design. Use when user asks about API design, REST… - 95add-command
Add support for a new CLI command. Use when implementing a handler or adding to SIMPLE_SAFE.