CLI Reference¶
Commands¶
zae-limiter¶
zae-limiter infrastructure management CLI.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--version |
boolean | Show the version and exit. | False |
--help |
boolean | Show this message and exit. | False |
Subcommands
- audit: Audit log commands.
- cfn-template: Export CloudFormation template for custom deployment.
- check: Check infrastructure compatibility without modifying.
- delete: Delete CloudFormation stack and all resources.
- deploy: Deploy CloudFormation stack with DynamoDB table and Lambda aggregator.
- entity: Entity-level limit configuration.
- lambda-export: Export Lambda deployment package for custom deployment.
- limits: Declarative limits management.
- list: List all deployed rate limiter instances in the region.
- loadtest: Load testing commands for zae-limiter.
- local: Local development with LocalStack.
- namespace: Namespace management commands.
- resource: Resource-level default limit configuration.
- status: Get comprehensive status of rate limiter infrastructure.
- system: System-level default limit configuration.
- upgrade: Upgrade infrastructure to match client version.
- usage: Usage snapshot commands.
- version: Show infrastructure version information.
zae-limiter audit¶
Audit log commands.
Query audit events for entities. Events track configuration changes like limits_set, entity_created, and entity_deleted.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- list: List audit events for an entity.
zae-limiter audit list¶
List audit events for an entity.
Shows configuration changes like limits_set, entity_created, entity_deleted. Results are ordered by timestamp (newest first).
Examples:
Sample Output:
Audit Events for: user-123
Timestamp Action Principal Resource
─────────────────────── ───────────── ────────── ────────
2026-01-15T10:30:00Z limits_set admin gpt-4
2026-01-15T10:25:00Z entity_created admin -
Total: 2 events
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--entity-id, -e |
text | Entity ID to query audit events for | Sentinel.UNSET |
--limit, -l |
integer | Maximum number of events to return (default: 100) | 100 |
--start-event-id |
text | Event ID to start after (for pagination) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter cfn-template¶
Export CloudFormation template for custom deployment.
Outputs the raw CloudFormation YAML template for manual deployment, integration with CDK/Terraform, or customization.
Examples:
# Export to file
zae-limiter cfn-template --output template.yaml
# Pipe to stdout
zae-limiter cfn-template > template.yaml
# View in pager
zae-limiter cfn-template | less
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output, -o |
path | Output file (default: stdout) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter check¶
Check infrastructure compatibility without modifying.
Verifies that the client version is compatible with the deployed infrastructure. Read-only operation - does not change anything.
Examples:
zae-limiter check --name my-app --region us-east-1
zae-limiter check --endpoint-url http://localhost:4566
Sample Output:
Compatibility Check
====================
Client: 0.6.0
Schema: 0.6.0
Lambda: 0.6.0
Result: COMPATIBLE
Client and infrastructure are fully compatible.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter delete¶
Delete CloudFormation stack and all resources.
Removes the DynamoDB table, Lambda function, IAM roles, and all associated resources. This action cannot be undone - all data will be permanently lost.
Examples:
# Delete with confirmation prompt
zae-limiter delete --name my-app --region us-east-1
# Skip confirmation (for scripts)
zae-limiter delete --name my-app --yes
# Delete without waiting
zae-limiter delete --name my-app --no-wait
Data Loss
Deleting a stack removes the DynamoDB table and all its data. This action cannot be undone.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name | Sentinel.UNSET |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--wait / --no-wait |
boolean | Wait for stack deletion to complete | True |
--yes, -y |
boolean | Skip confirmation prompt | False |
--help |
boolean | Show this message and exit. | False |
zae-limiter deploy¶
Deploy CloudFormation stack with DynamoDB table and Lambda aggregator.
Creates or updates infrastructure including DynamoDB table, Lambda aggregator for usage snapshots, CloudWatch alarms, and IAM roles. On first deploy, also registers the "default" namespace. The stack is idempotent - running deploy again updates existing resources.
Examples:
# Basic deployment
zae-limiter deploy --name my-app --region us-east-1
# Production with deletion protection and tracing
zae-limiter deploy --name prod --region us-east-1 \
--enable-deletion-protection --enable-tracing
# Without Lambda aggregator (table only)
zae-limiter deploy --name simple --no-aggregator
# LocalStack development
zae-limiter deploy --name dev \
--endpoint-url http://localhost:4566
# Enterprise with permission boundary
zae-limiter deploy --name prod \
--permission-boundary arn:aws:iam::aws:policy/PowerUserAccess \
--role-name-format "pb-{}-PowerUser"
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--snapshot-windows |
text | Comma-separated list of snapshot windows | hourly,daily |
--usage-retention-days |
integer | Number of days to retain usage snapshots | 90 |
--audit-retention-days |
integer | Number of days to retain audit records (default: 90) | 90 |
--enable-aggregator / --no-aggregator |
boolean | Deploy Lambda aggregator for usage snapshots | True |
--pitr-recovery-days |
integer | Point-in-Time Recovery period in days (1-35, default: AWS default of 35) | Sentinel.UNSET |
--log-retention-days |
choice (1 | 3 | 5 | 7 | 14 | 30 | 60 | 90 | 120 | 150 | 180 | 365 | 400 | 545 | 731 | 1096 | 1827 | 2192 | 2557 | 2922 | 3288 | 3653) |
Number of days to retain Lambda logs (CloudWatch standard retention periods) | 30 |
--lambda-timeout |
integer range (between 1 and 900) |
Lambda timeout in seconds (1-900, default: 60) | 60 |
--lambda-memory |
integer range (between 128 and 3008) |
Lambda memory size in MB (128-3008, default: 256) | 256 |
--enable-alarms / --no-alarms |
boolean | Deploy CloudWatch alarms for monitoring (default: enabled) | True |
--alarm-sns-topic |
text | SNS topic ARN for alarm notifications (optional) | None |
--lambda-duration-threshold-pct |
integer range (between 1 and 100) |
Lambda duration alarm threshold as percentage of timeout (1-100, default: 80) | 80 |
--wait / --no-wait |
boolean | Wait for stack creation to complete | True |
--permission-boundary |
text | IAM permission boundary for Lambda role (policy name or full ARN) | None |
--role-name-format |
text | Format template for role name. Use {} as placeholder for default name. Example: 'pb-{}' produces 'pb-mystack-aggr'. | None |
--policy-name-format |
text | Format template for managed policy name. Use {} as placeholder for default name. Example: 'pb-{}' produces 'pb-mystack-app'. | None |
--enable-audit-archival / --no-audit-archival |
boolean | Archive expired audit events to S3 (default: enabled) | True |
--audit-archive-glacier-days |
integer range (between 1 and 3650) |
Days before transitioning audit archives to Glacier Instant Retrieval (default: 90) | 90 |
--enable-tracing / --no-tracing |
boolean | Enable AWS X-Ray tracing for Lambda aggregator (default: disabled) | False |
--create-iam-roles / --no-create-iam-roles |
boolean | Create App/Admin/ReadOnly IAM roles (default: disabled). Policies always created. | False |
--iam / --no-iam |
boolean | Create IAM resources (policies, roles). --no-iam skips all IAM. | True |
--aggregator-role-arn |
text | Use existing IAM role ARN for Lambda aggregator (enables aggregator with --no-iam). | None |
--enable-deletion-protection / --no-deletion-protection |
boolean | Enable DynamoDB table deletion protection (default: disabled) | False |
--tag, -t |
text | User-defined tag in KEY=VALUE format. Can be specified multiple times. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter entity¶
Entity-level limit configuration.
Manage entities (users, API keys, projects) and their custom limits. Entity limits have highest priority, overriding resource and system defaults.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- create: Create a new entity.
- delete-limits: Delete limits for a specific entity and resource.
- get-limits: Get limits for a specific entity and resource.
- list: List entities with custom limit configurations.
- list-resources: List resources with entity-level custom limit configurations.
- set-limits: Set limits for a specific entity and resource.
- show: Show details for an entity.
zae-limiter entity create¶
Create a new entity.
ENTITY_ID is the unique identifier for the entity (e.g., 'user-123', 'api-key-abc').
Examples:
# Create a standalone entity
zae-limiter entity create user-123
# Create with display name
zae-limiter entity create api-key-abc --display-name "Production API"
# Create with parent and cascade
zae-limiter entity create user-123 --parent org-456 --cascade
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--display-name |
text | Human-readable name (defaults to entity_id) | None |
--parent |
text | Parent entity ID (for hierarchical limits) | None |
--cascade / --no-cascade |
boolean | Enable cascade: acquire() also consumes from parent entity | False |
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter entity delete-limits¶
Delete limits for a specific entity and resource.
ENTITY_ID is the entity to delete limits from (e.g., 'user-123', 'api-key-abc').
Examples:
# Delete with confirmation
zae-limiter entity delete-limits user-premium --resource gpt-4
# Skip confirmation
zae-limiter entity delete-limits user-premium -r gpt-4 --yes
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--resource, -r |
text | Resource name (e.g., 'gpt-4', 'default' for all resources). Default: default | _default_ |
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--yes, -y |
boolean | Skip confirmation prompt | False |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter entity get-limits¶
Get limits for a specific entity and resource.
ENTITY_ID is the entity to query (e.g., 'user-123', 'api-key-abc').
Examples:
zae-limiter entity get-limits user-premium --resource gpt-4
zae-limiter entity get-limits api-key-123 -r claude-3
Sample Output:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--resource, -r |
text | Resource name (e.g., 'gpt-4', 'default' for all resources). Default: default | _default_ |
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter entity list¶
List entities with custom limit configurations.
Uses GSI3 sparse index for efficient queries.
Examples:
# List entities with custom limits for gpt-4
zae-limiter entity list --with-custom-limits gpt-4
# List with a maximum of 10 results
zae-limiter entity list --with-custom-limits claude-3 --limit 10
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--with-custom-limits |
text | List entities with custom limits for this resource | Sentinel.UNSET |
--limit |
integer | Maximum number of entities to return | None |
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter entity list-resources¶
List resources with entity-level custom limit configurations.
Shows which resources have at least one entity with custom limits. Uses the entity config resources registry for fast O(1) lookup.
Examples:
Sample Output:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter entity set-limits¶
Set limits for a specific entity and resource.
ENTITY_ID is the entity to configure (e.g., 'user-123', 'api-key-abc'). Entity limits override resource and system defaults.
Examples:
# Set premium user limits for gpt-4
zae-limiter entity set-limits user-premium -r gpt-4 -l tpm:100000 -l rpm:1000
# Set limits for claude-3 with per-hour period
zae-limiter entity set-limits api-key-123 -r claude-3 -l tph:50000/hour
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--resource, -r |
text | Resource name (e.g., 'gpt-4', 'default' for all resources). Default: default | _default_ |
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--limit, -l |
text | Limit in 'name:rate[/period]' or 'name:rate[/period]:burst' format (repeatable). Period: /sec, /min (default), /hour, /day. | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter entity show¶
Show details for an entity.
ENTITY_ID is the entity to query (e.g., 'user-123', 'api-key-abc').
Examples:
Sample Output:
Entity: user-123
Name: Alice Smith
Parent: org-456
Cascade: True
Created: 2026-01-15T10:30:00Z
Metadata: {'tier': 'premium'}
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter lambda-export¶
Export Lambda deployment package for custom deployment.
Creates a ZIP file containing the Lambda aggregator code for manual deployment or inspection. Useful for custom deployment pipelines.
Examples:
# Export Lambda package
zae-limiter lambda-export --output lambda.zip
# Show package info without building
zae-limiter lambda-export --info
# Overwrite existing file
zae-limiter lambda-export --force
Sample Output (--info):
Lambda Package Information
==========================
Package path: /path/to/zae_limiter_aggregator
Python files: 4
Uncompressed size: 24.5 KB
Handler: zae_limiter_aggregator.handler.handler
Dependencies: 1
- aws-lambda-powertools
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output, -o |
path | Output file path (default: lambda.zip) | lambda.zip |
--info |
boolean | Show package information without building | False |
--force, -f |
boolean | Overwrite existing file without prompting | False |
--help |
boolean | Show this message and exit. | False |
zae-limiter limits¶
Declarative limits management.
Manage rate limits via YAML files. Apply through a Lambda provisioner that supports both CLI and CloudFormation paths.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- apply: Apply limits from YAML file (like terraform apply).
- cfn-template: Generate a CloudFormation template from YAML file.
- diff: Show drift between YAML and live DynamoDB state.
- plan: Preview changes without applying (like terraform plan).
zae-limiter limits apply¶
Apply limits from YAML file (like terraform apply).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | Sentinel.UNSET |
--region |
text | AWS region. | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., LocalStack). | Sentinel.UNSET |
--namespace, -N |
text | Namespace. | default |
--file, -f |
path | YAML limits file. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter limits cfn-template¶
Generate a CloudFormation template from YAML file.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier (for ImportValue). | Sentinel.UNSET |
--file, -f |
path | YAML limits file. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter limits diff¶
Show drift between YAML and live DynamoDB state.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | Sentinel.UNSET |
--region |
text | AWS region. | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., LocalStack). | Sentinel.UNSET |
--namespace, -N |
text | Namespace. | default |
--file, -f |
path | YAML limits file. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter limits plan¶
Preview changes without applying (like terraform plan).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | Sentinel.UNSET |
--region |
text | AWS region. | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., LocalStack). | Sentinel.UNSET |
--namespace, -N |
text | Namespace. | default |
--file, -f |
path | YAML limits file. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter list¶
List all deployed rate limiter instances in the region.
Discovers stacks by CloudFormation tags. Shows name, status, version, and creation date for each instance.
Examples:
Sample Output:
Rate Limiter Instances (us-east-1)
Name Status Version Created
────────── ───────────────── ──────── ──────────
my-app CREATE_COMPLETE 0.6.0 2026-01-15
prod-api UPDATE_COMPLETE 0.6.0 2026-01-10
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter loadtest¶
Load testing commands for zae-limiter.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- delete: Delete load test infrastructure.
- deploy: Deploy load test infrastructure.
- list: List deployed load test stacks.
- push: Rebuild and push locustfiles and Lambda code.
- run: Run a single load test execution.
- tune: Find optimal per-worker user count via binary search.
- ui: Open Locust web UI via SSM tunnel.
zae-limiter loadtest delete¶
Delete load test infrastructure.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | zae-limiter name | Sentinel.UNSET |
--region |
text | AWS region | None |
--yes |
boolean | Skip confirmation | False |
--help |
boolean | Show this message and exit. | False |
zae-limiter loadtest deploy¶
Deploy load test infrastructure.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | zae-limiter name | None |
--region |
text | AWS region | None |
--vpc-id |
text | VPC ID for load test resources | None |
--subnet-ids |
text | Comma-separated private subnet IDs | None |
--max-workers |
integer | Maximum Lambda workers (auto-scaling cap) | 100 |
--users-per-worker |
integer | Max users per Lambda worker for auto-scaling (default: 10) | 10 |
--min-workers |
integer | Minimum workers to maintain (default: 1) | 1 |
--startup-lead-time |
integer | Seconds to predict ahead for proactive scaling (default: 20) | 20 |
--lambda-timeout |
integer | Lambda worker timeout in minutes (default: 5) | 5 |
--lambda-memory |
integer | Lambda worker memory in MB (CPU scales with memory; 1769 MB = 1 vCPU, default: 1769) | 1769 |
--capacity-provider |
choice (FARGATE_SPOT | FARGATE) |
ECS capacity provider (default: FARGATE_SPOT) | FARGATE_SPOT |
--ssm-endpoint / --no-ssm-endpoint |
boolean | Create VPC endpoints for SSM (not needed if VPC has NAT gateway) | False |
--dynamodb-endpoint / --no-dynamodb-endpoint |
boolean | Create DynamoDB gateway endpoint (auto-discovers route tables) | True |
-C |
directory | Directory containing locustfiles (default: current directory) | . |
--help |
boolean | Show this message and exit. | False |
zae-limiter loadtest list¶
List deployed load test stacks.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--region |
text | AWS region | None |
--help |
boolean | Show this message and exit. | False |
zae-limiter loadtest push¶
Rebuild and push locustfiles and Lambda code.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | zae-limiter name | None |
--region |
text | AWS region | None |
-C |
directory | Directory containing locustfiles (default: current directory) | . |
--help |
boolean | Show this message and exit. | False |
zae-limiter loadtest run¶
Run a single load test execution.
Lambda mode (default): Invokes a single Lambda worker in headless mode. Use --workers N to run distributed (Fargate master + Lambda workers).
Optionally pass User class names to run specific classes (default: all).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | zae-limiter name | Sentinel.UNSET |
--region |
text | AWS region | None |
--users |
integer | Number of simulated users (default: 20) | 20 |
--duration |
integer | Test duration in seconds (default: 60) | 60 |
--spawn-rate |
integer | User spawn rate per second (default: 10) | 10 |
-f, --locustfile |
text | Locustfile path (e.g. locustfiles/max_rps.py) | Sentinel.UNSET |
--cpu |
integer | Override Fargate task CPU units (default from task def) | None |
--memory |
integer | Override Fargate task memory in MB (default from task def) | None |
--port |
integer | Local port for SSM tunnel (Fargate mode) | 8089 |
--workers |
integer | Number of Lambda workers (implies distributed mode) | None |
--help |
boolean | Show this message and exit. | False |
zae-limiter loadtest tune¶
Find optimal per-worker user count via binary search.
Uses Little's Law to binary-search for the optimal per-worker user count by measuring efficiency (baseline_p50 / observed_p50) at different concurrency levels. Lambda-only.
Optionally pass User class names to run specific classes (default: all).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | zae-limiter name | Sentinel.UNSET |
--region |
text | AWS region | None |
-f, --locustfile |
text | Locustfile path (e.g. locustfiles/max_rps.py) | Sentinel.UNSET |
--max-users |
integer | Upper bound for binary search (default: 40) | 40 |
--threshold |
float | Target efficiency ratio (default: 0.80) | 0.8 |
--step-duration |
integer | Seconds per tuning step (default: 30) | 30 |
--baseline-duration |
integer | Seconds for baseline phase (default: 60) | 60 |
--spawn-rate |
integer | User spawn rate per second (default: 10) | 10 |
--help |
boolean | Show this message and exit. | False |
zae-limiter loadtest ui¶
Open Locust web UI via SSM tunnel.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | zae-limiter name | Sentinel.UNSET |
--region |
text | AWS region | None |
--port |
integer | Local port for Locust UI | 8089 |
--destroy |
boolean | Stop Fargate on disconnect even if already running | False |
--force |
boolean | Stop existing task and restart with new config | False |
-f, --locustfile |
text | Locustfile path (relative to -C directory used in deploy) | Sentinel.UNSET |
--max-workers |
integer | Override max Lambda workers | None |
--min-workers |
integer | Override minimum workers | None |
--users-per-worker |
integer | Override users per worker ratio | None |
--startup-lead-time |
integer | Override predictive scaling lookahead | None |
--cpu |
integer | Override task CPU units (256, 512, 1024, 2048, 4096) | None |
--memory |
integer | Override task memory in MB | None |
--pool-connections |
integer | Override boto3 connection pool size (default: 1000) | None |
--help |
boolean | Show this message and exit. | False |
zae-limiter local¶
Local development with LocalStack.
Requires the [local] extra:
pip install 'zae-limiter[local]'
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- down: Stop LocalStack.
- env: Output LocalStack environment variables.
- logs: Show LocalStack container logs.
- status: Show LocalStack container status.
- up: Start LocalStack for local development.
zae-limiter local down¶
Stop LocalStack.
Examples:
zae-limiter local down
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--docker-host |
text | Docker daemon URL (e.g., unix:///path/to/docker.sock) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter local env¶
Output LocalStack environment variables.
Prints the environment variables needed to connect to LocalStack. Does not require Docker or a running container.
Examples:
eval "$(zae-limiter local env)" # bash/zsh
zae-limiter local env --format direnv > .envrc # direnv
zae-limiter local env --format powershell # PowerShell
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--format, -f |
choice (eval | direnv | powershell) |
Output format | eval |
--port |
integer | Host port for LocalStack endpoint | 4566 |
--help |
boolean | Show this message and exit. | False |
zae-limiter local logs¶
Show LocalStack container logs.
Examples:
# Show recent logs
zae-limiter local logs
# Follow logs
zae-limiter local logs --follow
# Show last 50 lines
zae-limiter local logs --tail 50
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--docker-host |
text | Docker daemon URL (e.g., unix:///path/to/docker.sock) | Sentinel.UNSET |
--follow, -f |
boolean | Follow log output | False |
--tail |
integer | Number of lines to show from end of logs | 100 |
--help |
boolean | Show this message and exit. | False |
zae-limiter local status¶
Show LocalStack container status.
Examples:
zae-limiter local status
Sample Output:
LocalStack: running
Endpoint: http://localhost:4566
Health: healthy
Image: localstack/localstack:4.14
Services: dynamodb,dynamodbstreams,lambda,cloudformation,...
To configure your shell:
eval "$(zae-limiter local env)" # bash/zsh
zae-limiter local env --format direnv > .envrc # direnv
zae-limiter local env --format powershell # PowerShell
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--docker-host |
text | Docker daemon URL (e.g., unix:///path/to/docker.sock) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter local up¶
Start LocalStack for local development.
Examples:
# Start LocalStack
zae-limiter local up
# Start with deploy instructions
zae-limiter local up --name my-app
# Use a different port
zae-limiter local up --port 4567
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--docker-host |
text | Docker daemon URL (e.g., unix:///path/to/docker.sock) | Sentinel.UNSET |
--image |
text | LocalStack Docker image | localstack/localstack:4.14 |
--name, -n |
text | Stack name to include in deploy instructions | None |
--port |
integer | Host port to bind LocalStack to | 4566 |
--help |
boolean | Show this message and exit. | False |
zae-limiter namespace¶
Namespace management commands.
Manage multi-tenant namespaces for isolated rate limiting. Each namespace has its own entities, buckets, and configurations.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- delete: Soft-delete a namespace (recoverable).
- list: List all active namespaces with IDs.
- orphans: List deleted namespaces with orphaned data.
- purge: Permanently delete all data for a namespace (IRREVERSIBLE).
- recover: Recover a deleted namespace by its ID.
- register: Register one or more namespaces.
- show: Show details for a specific namespace.
zae-limiter namespace delete¶
Soft-delete a namespace (recoverable).
NAMESPACE_NAME is the namespace to delete (e.g., 'tenant-alpha'). Data items are NOT deleted — they remain orphaned and can be recovered.
Examples:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--yes, -y |
boolean | Skip confirmation prompt | False |
--help |
boolean | Show this message and exit. | False |
zae-limiter namespace list¶
List all active namespaces with IDs.
Examples:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter namespace orphans¶
List deleted namespaces with orphaned data.
Examples:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter namespace purge¶
Permanently delete all data for a namespace (IRREVERSIBLE).
NAMESPACE_ID is the opaque namespace ID (e.g., 'aB3x_9Qw'). Use 'namespace orphans' to find deleted namespace IDs.
Examples:
Data Loss
Purging permanently deletes all entities, buckets, configs, and audit logs in the namespace. This cannot be undone.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--yes, -y |
boolean | Skip confirmation prompt | False |
--help |
boolean | Show this message and exit. | False |
zae-limiter namespace recover¶
Recover a deleted namespace by its ID.
NAMESPACE_ID is the opaque namespace ID (e.g., 'aB3x_9Qw'). Use 'namespace orphans' to find deleted namespace IDs.
Examples:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter namespace register¶
Register one or more namespaces.
NAMESPACES are the namespace names to register (e.g., 'tenant-alpha'). Multiple names can be provided for bulk registration.
Examples:
zae-limiter namespace register tenant-alpha --name my-app
zae-limiter namespace register tenant-alpha tenant-beta --name my-app
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter namespace show¶
Show details for a specific namespace.
NAMESPACE_NAME is the namespace to look up (e.g., 'tenant-alpha').
Examples:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter resource¶
Resource-level default limit configuration.
Configure default limits for specific resources (e.g., gpt-4, claude-3). Resource defaults override system defaults but are overridden by entity limits.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- delete-defaults: Delete default limits for a resource.
- get-defaults: Get default limits for a resource.
- list: List all resources with configured defaults.
- set-defaults: Set default limits for a resource.
zae-limiter resource delete-defaults¶
Delete default limits for a resource.
RESOURCE_NAME is the resource to delete defaults from (e.g., 'gpt-4', 'claude-3').
Examples:
# Delete with confirmation prompt
zae-limiter resource delete-defaults gpt-4
# Skip confirmation
zae-limiter resource delete-defaults gpt-4 --yes
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--yes, -y |
boolean | Skip confirmation prompt | False |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter resource get-defaults¶
Get default limits for a resource.
RESOURCE_NAME is the resource to query (e.g., 'gpt-4', 'claude-3').
Examples:
Sample Output:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter resource list¶
List all resources with configured defaults.
Examples:
Sample Output:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter resource set-defaults¶
Set default limits for a resource.
RESOURCE_NAME is the resource to configure (e.g., 'gpt-4', 'claude-3'). Resource defaults override system defaults for this specific resource.
Examples:
# Set TPM and RPM defaults for gpt-4
zae-limiter resource set-defaults gpt-4 -l tpm:100000 -l rpm:1000
# Set limits with explicit period
zae-limiter resource set-defaults gpt-4 -l rpm:1000/min -l tph:50000/hour
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--limit, -l |
text | Limit in 'name:rate[/period]' or 'name:rate[/period]:burst' format (repeatable). Period: /sec, /min (default), /hour, /day. | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter status¶
Get comprehensive status of rate limiter infrastructure.
Shows connectivity, stack status, version compatibility, table metrics, and IAM role ARNs. Read-only operation - does not modify any resources.
Examples:
zae-limiter status --name my-app --region us-east-1
zae-limiter status --name dev --endpoint-url http://localhost:4566
Sample Output:
Status: my-app
==================================================
Connectivity
Available: ✓ Yes
Latency: 42ms
Region: us-east-1
Infrastructure
Stack: CREATE_COMPLETE
Table: ACTIVE
Aggregator: Enabled
Versions
Client: 0.6.0
Schema: 0.6.0
Lambda: 0.6.0
Table Metrics
Items: 1,234
Size: 256 KB
✓ Infrastructure is ready
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name | Sentinel.UNSET |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
zae-limiter system¶
System-level default limit configuration.
Configure global defaults that apply to ALL resources unless overridden. System defaults are the lowest priority in the hierarchy.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- delete-defaults: Delete all system-wide default limits and config.
- get-defaults: Get system-wide default limits and config.
- set-defaults: Set system-wide default limits.
zae-limiter system delete-defaults¶
Delete all system-wide default limits and config.
Examples:
# Delete with confirmation prompt
zae-limiter system delete-defaults
# Skip confirmation
zae-limiter system delete-defaults --yes
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--yes, -y |
boolean | Skip confirmation prompt | False |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter system get-defaults¶
Get system-wide default limits and config.
Examples:
Sample Output:
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter system set-defaults¶
Set system-wide default limits.
System defaults apply to ALL resources unless overridden at resource or entity level.
Examples:
# Set global defaults
zae-limiter system set-defaults -l tpm:10000 -l rpm:100
# Set defaults with unavailability behavior
zae-limiter system set-defaults -l tpm:10000 --on-unavailable allow
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Stack identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack) | Sentinel.UNSET |
--limit, -l |
text | Limit in 'name:rate[/period]' or 'name:rate[/period]:burst' format (repeatable). Period: /sec, /min (default), /hour, /day. | Sentinel.UNSET |
--on-unavailable |
choice (allow | block) |
Behavior when DynamoDB is unavailable | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter upgrade¶
Upgrade infrastructure to match client version.
Updates Lambda code and version records to match the current client. Use --force to update even when versions already match.
Examples:
# Standard upgrade
zae-limiter upgrade --name my-app --region us-east-1
# Force Lambda update
zae-limiter upgrade --name my-app --force
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--lambda-only |
boolean | Only update Lambda code | False |
--force |
boolean | Force update even if version matches | False |
--help |
boolean | Show this message and exit. | False |
zae-limiter usage¶
Usage snapshot commands.
Query historical usage data aggregated by the Lambda aggregator. Snapshots track token consumption per entity/resource in hourly and daily windows.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
zae-limiter usage list¶
List usage snapshots.
Query historical token consumption data. Requires either --entity-id or --resource. Use --plot for ASCII chart visualization.
Examples:
zae-limiter usage list --entity-id user-123
zae-limiter usage list --resource gpt-4 --window hourly
zae-limiter usage list --entity-id user-123 --plot
Note
Either --entity-id or --resource must be provided.
ASCII Charts
The --plot flag requires the optional plot extra:
pip install 'zae-limiter[plot]'
Sample Output:
Usage Snapshots
Window Start Type Resource Entity Events Counters
──────────────────── ────── ──────── ──────── ────── ────────────────
2026-01-15T10:00:00Z hourly gpt-4 user-123 42 tpm=15,000
2026-01-15T09:00:00Z hourly gpt-4 user-123 38 tpm=12,500
Total: 2 snapshots
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--entity-id, -e |
text | Entity ID to query (required unless --resource is provided) | Sentinel.UNSET |
--resource, -r |
text | Resource name filter (required if --entity-id is not provided) | Sentinel.UNSET |
--window, -w |
choice (hourly | daily) |
Filter by window type | Sentinel.UNSET |
--start |
text | Start time (ISO format, e.g., 2024-01-01T00:00:00Z) | Sentinel.UNSET |
--end |
text | End time (ISO format, e.g., 2024-01-31T23:59:59Z) | Sentinel.UNSET |
--limit, -l |
integer | Maximum number of snapshots to return (default: 100) | 100 |
--plot, -p |
boolean | Display as ASCII charts instead of table (requires: pip install 'zae-limiter[plot]') | False |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter usage summary¶
Show aggregated usage summary.
Computes total and average consumption across matching snapshots. Useful for billing, reporting, and capacity planning.
Examples:
zae-limiter usage summary --entity-id user-123
zae-limiter usage summary --resource gpt-4 --window daily
Note
Either --entity-id or --resource must be provided.
Sample Output:
Usage Summary
Entity: user-123
Resource: gpt-4
Snapshots: 24
Time Range: 2026-01-14T00:00:00Z to 2026-01-15T23:00:00Z
Limit Total Average
───── ──────── ─────────
rpm 950 39.58
tpm 450,000 18,750.00
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--entity-id, -e |
text | Entity ID to query (required unless --resource is provided) | Sentinel.UNSET |
--resource, -r |
text | Resource name filter (required if --entity-id is not provided) | Sentinel.UNSET |
--window, -w |
choice (hourly | daily) |
Filter by window type | Sentinel.UNSET |
--start |
text | Start time (ISO format, e.g., 2024-01-01T00:00:00Z) | Sentinel.UNSET |
--end |
text | End time (ISO format, e.g., 2024-01-31T23:59:59Z) | Sentinel.UNSET |
--namespace, -N |
text | Namespace within the table (default: "default") | default |
--help |
boolean | Show this message and exit. | False |
zae-limiter version¶
Show infrastructure version information.
Displays client version, schema version, and deployed infrastructure versions. Checks compatibility between client and infrastructure.
Examples:
zae-limiter version --name my-app --region us-east-1
zae-limiter version --endpoint-url http://localhost:4566
Sample Output:
zae-limiter Infrastructure Version
====================================
Client Version: 0.6.0
Schema Version: 0.6.0
Infra Schema: 0.6.0
Lambda Version: 0.6.0
Min Client Version: 0.5.0
Status: COMPATIBLE
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--name, -n |
text | Resource identifier used as the CloudFormation stack name. | zae-limiter |
--region |
text | AWS region (default: use boto3 defaults) | Sentinel.UNSET |
--endpoint-url |
text | AWS endpoint URL (e.g., http://localhost:4566 for LocalStack, or other AWS-compatible services) | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
Environment Variables¶
The CLI respects standard AWS environment variables:
| Variable | Description |
|---|---|
AWS_ACCESS_KEY_ID |
AWS access key |
AWS_SECRET_ACCESS_KEY |
AWS secret key |
AWS_SESSION_TOKEN |
AWS session token |
AWS_DEFAULT_REGION |
Default AWS region |
AWS_PROFILE |
AWS profile name |
AWS_ENDPOINT_URL |
Custom endpoint URL |
Exit Codes¶
| Code | Description |
|---|---|
0 |
Success |
1 |
General error |
2 |
Invalid arguments |
3 |
AWS API error |
4 |
Stack not found |
Namespace Flag¶
Most data-access commands accept --namespace / -N to scope operations to a specific namespace. When omitted, operations default to the "default" namespace.
Namespace auto-registration
Data-access commands internally use Repository.open(), which auto-registers the namespace if it doesn't exist yet. The "default" namespace is always registered automatically.
# Entity operations in a specific namespace
zae-limiter entity set-limits user-123 --namespace tenant-alpha -l rpm:1000
# System defaults for a namespace
zae-limiter system set-defaults --namespace tenant-alpha -l rpm:5000
# Usage and audit scoped to a namespace
zae-limiter usage list --namespace tenant-alpha
zae-limiter audit list --namespace tenant-alpha
Declarative Limits¶
The limits command group manages rate limits declaratively via YAML manifest files. Changes are applied through a Lambda provisioner that tracks managed state and computes diffs, similar to how terraform plan and terraform apply work.
YAML Manifest Format¶
namespace: default
system:
on_unavailable: block
limits:
rpm:
capacity: 1000
tpm:
capacity: 100000
resources:
gpt-4:
limits:
rpm:
capacity: 500
tpm:
capacity: 50000
gpt-3.5-turbo:
limits:
rpm:
capacity: 2000
tpm:
capacity: 500000
entities:
user-premium:
resources:
gpt-4:
limits:
rpm:
capacity: 1000
tpm:
capacity: 100000
Only capacity is required per limit. Defaults: refill_amount = capacity, refill_period = 60 seconds.
Preview Changes¶
Output:
Plan: 4 change(s)
+ create system: (system defaults)
+ create resource: gpt-4
+ create resource: gpt-3.5-turbo
+ create entity: user-premium/gpt-4
Apply Changes¶
Output:
+ create system: (system defaults)
+ create resource: gpt-4
+ create resource: gpt-3.5-turbo
+ create entity: user-premium/gpt-4
Applied: 4 created, 0 updated, 0 deleted.
Subsequent applies with a modified YAML file will show ~ for updates and - for deletions (items removed from the manifest are deleted from DynamoDB).
Detect Drift¶
Output (when live state differs from YAML):
Generate CloudFormation Template¶
# Generate a CFN template with Custom::ZaeLimiterLimits resource
zae-limiter limits cfn-template -n my-app -f limits.yaml > limits-stack.yaml
# Deploy with AWS CLI
aws cloudformation deploy \
--template-file limits-stack.yaml \
--stack-name my-app-limits
The generated template uses Custom::ZaeLimiterLimits backed by the provisioner Lambda. The Lambda ARN is imported from the main stack via Fn::ImportValue.
Common Options¶
| Option | Short | Description |
|---|---|---|
--name |
-n |
Stack identifier (required) |
--file |
-f |
Path to YAML limits file (required) |
--region |
AWS region | |
--endpoint-url |
Custom endpoint URL (e.g., LocalStack) | |
--namespace |
-N |
Namespace (default: "default") |
Provisioner Lambda
The plan, apply, and diff subcommands invoke the {name}-limits-provisioner Lambda function. This function must be deployed as part of the main stack before using these commands.
Namespace Lifecycle¶
The namespace command group manages the namespace registry:
# Register namespaces
zae-limiter namespace register tenant-alpha tenant-beta
# List active namespaces
zae-limiter namespace list
# Show namespace details (including opaque ID)
zae-limiter namespace show tenant-alpha
# Soft delete (data preserved, forward lookup removed)
zae-limiter namespace delete tenant-alpha
# Recover a soft-deleted namespace
zae-limiter namespace recover <namespace-id>
# List deleted namespaces (candidates for purge)
zae-limiter namespace orphans
# Hard delete all data in a namespace (irreversible)
zae-limiter namespace purge <namespace-id> --yes