The domain add command adds an already-registered root domain to your AWS account so Stacktape can manage DNS and TLS certificates for it. Once added, the domain and its subdomains can be used with web services, hosting buckets, HTTP API Gateways, and WebSocket API Gateways. The command requires --region and, on success, finishes with Domain ready to use in <region>.
Usage
The command runs an interactive wizard. You supply only the --region flag — the domain name is entered interactively during the wizard.
What it does
The domain add wizard walks through the following steps, stopping at the first incomplete one.
- Enter domain name — Must be a root domain (e.g.
mydomain.com, notsub.mydomain.com). If you enter a subdomain, the command exits with an error. - Check registration — If the domain is not registered (not purchased), the command exits immediately and prints a hint to register via Route 53 or another registrar. Prices start at $3/year for
.clickdomains. - Verify DNS ownership — If DNS is managed outside AWS, the command asks whether to move DNS management to Route 53. If confirmed and no hosted zone exists, it creates one and prints the name servers to configure at your registrar.
- Provision TLS certificates — Requests a regional ACM certificate. When the selected region is not
us-east-1, the command also requests aus-east-1ACM certificate, which Stacktape stores asusEast1Certin domain status. When the regional certificate is not yet issued, it adds a DNS validation record from the regional certificate's domain validation options to the Route 53 hosted zone.
The command stores domain status in Parameter Store after key checkpoints (hosted-zone setup, certificate-validation-record setup), so later runs can read saved domain status. Re-run domain add after DNS or certificate validation has had time to complete.
api.mydomain.com, the command exits with an error. Add the root domain (mydomain.com) first, then configure subdomains on the resource that should serve them. See custom domains for the resource-level setup.DNS ownership scenarios
The command handles two scenarios based on the domain's DNS ownership status.
DNS already verified
If Stacktape detects that domain ownership is already verified, the command skips straight to TLS certificate provisioning.
DNS managed outside AWS
When DNS for the domain is managed outside AWS, the command asks whether you want to move DNS management to Route 53. If you confirm:
- A Route 53 hosted zone is created (if one doesn't already exist).
- The command prints the name server records to set at your registrar.
- DNS propagation can take hours to days depending on the registrar and prior TTL values.
- After propagation, re-run
domain addto continue with certificate provisioning.
TLS certificates
The command requests a free AWS ACM certificate in the specified --region. When the selected region is not us-east-1, the command also requests a us-east-1 ACM certificate, which Stacktape stores as usEast1Cert in domain status. When the regional certificate is not yet issued, the command adds a DNS validation record from the regional certificate's domain validation options to the Route 53 hosted zone. Certificate issuance typically takes a few minutes after DNS records are in place.
Arguments reference
stacktape domain addCLI options-r, --regionrequired"us-east-2" | "us-east-1" | "us-west-1" | "us-west-2" | "ap-east-1" | "ap-south-1" | "ap-northeast-3" | "ap-northeast-2" | "ap-southeast-1" | "ap-southeast-2" | "ap-northeast-1" | "ca-central-1" | "eu-central-1" | "eu-west-1" | "eu-west-2" | "eu-west-3" | "eu-north-1" | "me-south-1" | "sa-east-1" | "af-south-1" | "eu-south-1"AWS Region
The AWS region for the operation. For a list of available regions, see the AWS documentation.
Inside a project whose config declares region, the flag is optional and overrides the config.
--aws-accountstringAWS Account
The name of the AWS account to use for the operation. The account must first be connected in the Stacktape Console.
Without it, the account is chosen by --profile, AWS_PROFILE or AWS credentials in environment variables, then by your saved default, then by your organization's only connected account. --aws-account takes precedence over all of them, but AWS credentials in environment variables must then belong to that account.
-h, --helpstringShow Help
If provided, the command will not execute and will instead print help information.
--log-level"info" | "debug" | "error"Log Level
The level of logs to print to the console.
info: Basic information about the operation.error: Only errors.debug: Detailed information for debugging.
-p, --profilestringAWS Profile
The AWS profile to use for the command. You can manage profiles using the aws-profile:* commands and set a default profile with defaults set.
For commands that use a connected AWS account, --profile (or AWS_PROFILE) selects the connected account the profile belongs to, unless --aws-account is set. The command fails if that account is not connected.
--quietbooleanQuiet
Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.
Examples
Add a domain in the eu-west-1 region:
Add a domain using a specific AWS profile:
Add a domain using a named AWS account connected in the Stacktape Console:
Related commands
deploy— deploy your stack, which can reference the added domain via custom domain configurationdefaults set— set a default region so you don't need--regionevery time
domain add FAQ
Can I add a subdomain instead of a root domain?
No. The domain add command only accepts root domains (e.g. mydomain.com). Entering a subdomain like api.mydomain.com causes the command to exit with an error. Add the root domain first, then configure subdomains on the resource that should serve them. See custom domains for the resource-level setup.
What happens if my domain is not yet registered?
If the domain is not registered (not purchased from any registrar), the command exits immediately and prints a hint to register it. You can register it with Route 53 or any other domain registrar. Registration prices vary by top-level domain; see the current Route 53 prices. After registration, re-run domain add.
Do I need to run this command in every region?
The command creates a regional certificate for the selected --region and, when that region is not us-east-1, also requests a us-east-1 ACM certificate stored as usEast1Cert in domain status. Run the command in each region where you intend regional certificates for the domain.
Is there a cost for adding a domain?
Adding the domain is free: ACM TLS certificates are free. The only cost is the underlying domain registration itself — Route 53 prices start at $3/year for .click domains, but registration is a separate step (domain add requires the domain to already be registered).
Can I use a domain registered outside AWS?
Yes. For domains registered with another registrar (GoDaddy, Namecheap, Hostinger, etc.), the command asks whether to move DNS management to Route 53. If you confirm, it creates a hosted zone (if needed) and prints the name servers to set at your registrar. If the domain is already serving traffic, copy your existing DNS records into the new hosted zone before switching name servers to avoid downtime. After DNS propagation, re-run the command to continue with certificate provisioning.