Add a first-class teardown command that reports what it retained
- Dominant language
- TypeScript
- Stars
- 283
- Forks
- 95
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 183
Description
### Description
There is no `agentcore destroy`, or any teardown or decommission command. `agentcore remove` only edits local `agentcore.json`, and `agentcore stop` covers A/B tests and batch evaluations.
The only way to tear a project down through the CLI is undocumented: empty every resource array in `agentcore.json`, then run `agentcore deploy --yes`, which triggers a full `cdk destroy`. That works, and the output does show a `Tear down stack` step, but it has four problems:
1. **It is undiscoverable.** It appears in neither `agentcore deploy --help` nor `agentcore help modes`. We only found it by reading the CLI source.
2. **It is spelled as a deploy.** `agentcore deploy` to destroy everything reads as the opposite of what it does, which is an uncomfortable command to hand to an operator whose intent is deletion.
3. **It requires the project's secrets present just to tear down.** With no `agentcore/.env.local`, the deploy fails asking for `AGENTCORE_CREDENTIAL_`. So a fresh clone, or a new machine, cannot retire a project until the operator recreates the very secrets they intend to destroy. We hit this on a real retirement where the credential no longer mattered.
4. **It silently leaves resources behind.** Lambda log groups carry `DeletionPolicy: Retain`, so a teardown orphans one per Container runtime. `cdk diff` shows this correctly as `orphan`, but the CLI's own output never mentions that anything was retained. Repeated create-and-retire cycles accumulate orphans indefinitely.
Retaining logs may well be intentional, and there is a reasonable case for it. The gap is that it is invisible: the information exists inside the CLI's own diff and never reaches the operator.
Combined with the missing credential-provider deletion in #2022, a "successful" teardown today can leave an orphaned credential provider, its backing secret, and one log group per runtime, with nothing reporting any of it.
### Acceptance Criteria
- [ ] A documented teardown command exists, for example `agentcore destroy --target `, discoverable from `--help`.
- [ ] It deletes the project's CloudFormation stack.
- [ ] It deletes each API-key credential provider the project owns, or clearly reports each one the operator must delete manually, with the exact command.
- [ ] It reports every resource the stack retained rather than deleted, naming each one, so the operator knows what remains in the account.
- [ ] It does not require credential secrets to be present in order to tear down, since the secrets are being destroyed.
- [ ] It requires explicit confirmation before deleting, consistent with the existing `--yes` gate on the current teardown path.
- [ ] Tearing down a project and then listing account resources leaves no untracked leftovers attributable to that project, or every leftover was named in the command's output.
### Additional Context
Verified on `@aws/agentcore` 0.27.0 (macOS, Node v22.22.1, `aws-cdk` 2.1126.0, `managedBy: CDK`, Container builds) using a throwaway two-runtime project created specifically to test teardown behavior.
What we observed after a teardown that reported success:
```bash
aws cloudformation describe-stacks --stack-name AgentCore-RetireTest- --region us-east-1
# Stack does not exist. Correct.
aws logs describe-log-groups --log-group-name-prefix "/aws/lambda/AgentCore-RetireTest" --region us-east-1
# 2 log groups still present, one per runtime:
# /aws/lambda/AgentCore-RetireTest-jobb-ApplicationAgentAlphaAmp-...
# /aws/lambda/AgentCore-RetireTest-jobb-ApplicationAgentBetaAmpC-...
aws bedrock-agentcore-control list-api-key-credential-providers --region us-east-1
# the project's provider still present (#2022)
```
The teardown output that preceded it gave no indication anything survived:
```text
✓ Deploy to AWS
✓ Tear down stack
✓ Deployed to '' (stack: AgentCore-RetireTest-)
```
Worth noting that **single-runtime** retirement already works well, and could serve as the model. `agentcore remove agent --name --yes` followed by `agentcore deploy` correctly scoped the CDK diff to just that runtime, spared the sibling runtime entirely, and narrowed the shared container-build IAM policy rather than deleting it. The only gap there is the same retained log group. So the mechanism is sound; what's missing is a command named for the intent, plus reporting of what it left behind.
Because of the gaps we ended up writing an internal wrapper that deletes the stack, then each credential provider, then each retained log group, and verifies all three. A documented `agentcore destroy` would let us delete that wrapper.
Contributor guide
Research direction
Start by tracing the existing `agentcore deploy --yes` teardown path and the `agentcore deploy --help` and `agentcore help modes` entry points. Compare its behavior with `agentcore remove agent --name --yes`, the CDK diff, and the observed AWS resources. Done means a documented, confirmed teardown command that works without secrets and reports every retained or manually deletable resource, including credential providers and log groups.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- cli, cloud, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100