CLI Reference - Local Web Services

LDK Commands

uvx --from local-web-services ldk dev [OPTIONS]

ldk dev

Start the full local environment with hot-reload. Watches your source files and restarts handlers on change.

--port, -p API Gateway listen port (default: 3000)
--no-persist Disable data persistence — data is lost when ldk stops
--force-synth Force CDK synth even if cdk.out exists
--log-level, -l Log level: debug, info, warning, error (default: info)
--project-dir, -d Project root directory (default: current directory)
--mode, -m Project mode: cdk or terraform (default: auto-detect from project files)
--background, -b Run in the background as a detached process. Logs are written to .lws/ldk-dev.log. Stop with ldk stop.

uvx --from local-web-services ldk stop [OPTIONS]

ldk stop

Stop a background ldk dev session. Sends a graceful shutdown signal via the management API.

--port, -p Port of the running ldk dev instance to stop (default: 3000)

uvx --from local-web-services ldk invoke [OPTIONS]

ldk invoke

Invoke a Lambda function directly with a JSON event payload. Useful for testing handlers in isolation.

--function-name, -f Lambda function name (required)
--event, -e Inline JSON event payload
--event-file Path to JSON event file
--project-dir, -d Project root directory (default: current directory)
--port, -p Management API port to connect to running ldk dev

uvx --from local-web-services ldk reset [OPTIONS]

ldk reset

Clear all persisted local state — databases, queues, buckets. Start fresh.

--yes, -y Skip confirmation prompt
--project-dir, -d Project root directory (default: current directory)
--port, -p Management API port to notify running ldk dev

uvx --from local-web-services ldk setup SERVICE [OPTIONS]

ldk setup

Pull Docker images required for local service emulation. Currently supports lambda which pulls official AWS Lambda base images from ECR Public (includes AWS SDK pre-installed).

SERVICE Service to set up (currently: lambda)
--runtime, -r Pull only a specific runtime (e.g. python3.12, nodejs20.x)

# Pull all Lambda runtime images
uvx --from local-web-services ldk setup lambda

# Pull a specific runtime only
uvx --from local-web-services ldk setup lambda --runtime python3.12

LWS Commands

AWS CLI-style commands for interacting with your local services. Requires a running ldk dev instance.

lws init

Initialize Claude Code integration. Creates CLAUDE.md context and slash commands for AI-assisted fake and chaos workflows.

--project-dir

uvx --from local-web-services lws init

lws status

Show the status of the running ldk dev instance and all providers.

uvx --from local-web-services lws status

lws dynamodb

DynamoDB table operations.

put-item get-item delete-item scan query

uvx --from local-web-services lws dynamodb scan \
  --table-name MyTable

lws sqs

SQS queue operations.

send-message receive-message delete-message get-queue-attributes

uvx --from local-web-services lws sqs receive-message \
  --queue-name MyQueue

lws s3api

S3 bucket operations.

put-object get-object delete-object list-objects-v2 head-object put-bucket-website get-bucket-website delete-bucket-website

uvx --from local-web-services lws s3api list-objects-v2 \
  --bucket my-bucket

lws sns

SNS topic operations.

publish list-topics list-subscriptions

uvx --from local-web-services lws sns publish \
  --topic-name MyTopic \
  --message "Hello"

lws events

EventBridge operations.

put-events list-rules

uvx --from local-web-services lws events put-events \
  --entries '[{...}]'

lws stepfunctions

Step Functions operations.

start-execution describe-execution list-executions list-state-machines

uvx --from local-web-services lws stepfunctions start-execution \
  --name MyStateMachine \
  --input '{...}'

lws cognito-idp

Cognito User Pool operations.

sign-up confirm-sign-up initiate-auth

uvx --from local-web-services lws cognito-idp sign-up \
  --user-pool-name MyPool \
  --username user@example.com

lws ssm

SSM Parameter Store operations.

put-parameter get-parameter get-parameters-by-path delete-parameter

uvx --from local-web-services lws ssm put-parameter \
  --name /app/config/key \
  --value "my-value" \
  --type String

lws secretsmanager

Secrets Manager operations.

create-secret get-secret-value put-secret-value list-secrets

uvx --from local-web-services lws secretsmanager create-secret \
  --name MySecret \
  --secret-string "my-secret-value"

lws apigateway

API Gateway test invocation.

test-invoke-method

uvx --from local-web-services lws apigateway test-invoke-method \
  --resource /orders \
  --http-method GET

lws fake

Fake server management. Create and manage fake HTTP/GraphQL/gRPC servers for external API dependencies.

create delete list status add-route remove-route import-spec validate chaos invoke

# Create a fake server
uvx --from local-web-services lws fake create --name stripe-api

# Add a route
uvx --from local-web-services lws fake add-route \
  --name stripe-api \
  --method POST --path /v1/charges \
  --status 200 --body '{"id": "ch_{{uuid}}"}'

# Import from OpenAPI spec
uvx --from local-web-services lws fake import-spec \
  --name stripe-api \
  --spec openapi.yaml

# Enable chaos testing
uvx --from local-web-services lws fake chaos \
  --name stripe-api \
  --error-rate 0.1

lws aws-fake

AWS operation faking. Override individual AWS API operations with custom responses.

create delete list status add-operation remove-operation enable disable

# Create an AWS fake for S3
uvx --from local-web-services lws aws-fake create my-s3-fake --service s3

# Fake a DynamoDB GetItem with a helper
uvx --from local-web-services lws aws-fake add-operation my-ddb-fake \
  --operation get-item \
  --item '{"id": "123", "name": "test"}'

# Fake an S3 GetObject
uvx --from local-web-services lws aws-fake add-operation my-s3-fake \
  --operation get-object \
  --body-string "Hello from S3"

# Enable/disable at runtime
uvx --from local-web-services lws aws-fake enable s3
uvx --from local-web-services lws aws-fake disable s3

lws chaos

Chaos engineering for AWS services. Inject errors, latency, timeouts, and connection resets into local service emulations.

enable disable set status

# Enable chaos on DynamoDB
uvx --from local-web-services lws chaos enable dynamodb

# Set error rate and latency
uvx --from local-web-services lws chaos set dynamodb \
  --error-rate 0.1 \
  --latency-min 50 --latency-max 200

# Check status
uvx --from local-web-services lws chaos status

# Disable
uvx --from local-web-services lws chaos disable dynamodb

lws iam-auth

IAM authorization management. Audit, ignore, or enforce IAM permissions on local AWS services.

status enable disable set set-identity

# Check IAM auth status
uvx --from local-web-services lws iam-auth status

# Enforce IAM on DynamoDB (deny unauthorized requests)
uvx --from local-web-services lws iam-auth set dynamodb --mode enforce

# Audit mode (log violations without blocking)
uvx --from local-web-services lws iam-auth set s3 --mode audit

# Switch active identity
uvx --from local-web-services lws iam-auth set-identity readonly-user

# Disable IAM auth for a service
uvx --from local-web-services lws iam-auth disable sqs