This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

# Configuring your CDK Toolkit instance
<a name="toolkit-library-configure"></a>

Learn how to customize your AWS CDK Toolkit Library instance with options for message handling, AWS profile selection, and stack selection strategies. This guide explains the available configuration options and how to implement them effectively to meet your specific deployment requirements.

## Configuring your AWS profile
<a name="toolkit-library-configure-profile"></a>

When you use the CDK Toolkit Library, it makes API calls to AWS using the SDK. While authentication is loaded automatically from your environment, you can explicitly specify which profile to use:

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
  sdkConfig: { profile: "my-profile" },
});
```

## Configuring stack selection
<a name="toolkit-library-configure-stacks"></a>

Most CDK Toolkit actions require you to specify which stacks to operate on. The ` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) ` configuration controls this selection.

### Select all stacks
<a name="toolkit-library-configure-stacks-all"></a>

Use this when you want to operate on every stack in your CDK app:

```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.ALL_STACKS
  }
});
```

### Select only main assembly stacks
<a name="toolkit-library-configure-stacks-main"></a>

Use this to select only the top-level stacks from the main assembly:

```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.MAIN_ASSEMBLY
  }
});
```

### Select a single stack
<a name="toolkit-library-configure-stacks-single"></a>

Use this when your assembly contains exactly one stack and you want to assert this condition. If the assembly includes a single stack, it returns that stack. Otherwise, it throws an exception:

```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.ONLY_SINGLE
  }
});
```

### Select stacks by pattern
<a name="toolkit-library-configure-stacks-pattern"></a>

Use this to select specific stacks by name pattern:

```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["Dev-*", "Test-Backend"],  // Supports wildcards
  }
});
```

**Tip**  
Use `PATTERN_MUST_MATCH_SINGLE` to ensure exactly one stack matches your patterns, or `PATTERN_MATCH` if it’s acceptable for no stacks to match. Pattern matching supports wildcards like "\$1" to match multiple stacks with similar names.

## Configuring error handling
<a name="toolkit-library-configure-errors"></a>

The CDK Toolkit uses structured errors to help you identify and handle issues. Each error includes:
+ A **source** indicating where the error originated (toolkit or user).
+ A specific **error type** (authentication, validation, etc.).
+ A descriptive **message**.

### Handling errors
<a name="toolkit-library-configure-errors-how"></a>

Use the helper methods provided by the CDK Toolkit to detect and handle specific error types:

```
import { ToolkitError } from '@aws-cdk/toolkit-lib';

try {
  // Attempt a CDK Toolkit operation
  await toolkit.deploy(cloudAssemblySource, {
    stacks: { strategy: StackSelectionStrategy.ALL_STACKS }
  });

} catch (error) {
  // Handle specific error types
  if (ToolkitError.isAuthenticationError(error)) {
    // Example: AWS credentials are missing or invalid
    console.error('Authentication failed. Check your AWS credentials.');

  } else if (ToolkitError.isAssemblyError(error)) {
    // Example: Your CDK app has errors in stack definitions
    console.error('CDK app error:', error.message);

  } else if (ToolkitError.isDeploymentError(error)) {
    // Example: CloudFormation deployment failed
    console.error('Deployment failed:', error.message);

  } else if (ToolkitError.isToolkitError(error)) {
    // Handle all other Toolkit errors
    console.error('CDK Toolkit error:', error.message);

  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}
```

**Important**  
Don’t rely on `instanceof` checks for error types, as they can behave unexpectedly when working with multiple copies of the same package. Always use the provided helper methods like `ToolkitError.isAuthenticationError()`.

## Configuring Toolkit actions
<a name="toolkit-library-configure-actions"></a>

Each CDK Toolkit action (deploy, synth, list, etc.) has its own specific configuration options. These actions allow you to manage the complete lifecycle of your CDK infrastructure. For detailed information on configuring individual actions, see [Configure CDK Toolkit programmatic actions](toolkit-library-actions.md).

**Tip**  
When building automation workflows, consider combining multiple actions in sequence. For example, you might want to `synth` your app, `list` the stacks to verify what will be deployed, and then `deploy` the infrastructure.