vk cert

Usage

vk cert request --domain <name> [options]

Most VentureKit projects host their DNS outside Route 53 (Cloudflare, Namecheap, …), where “create a certificate and validate it via DNS” is a manual copy-paste ritual against the AWS console. vk cert request compresses that ritual:

1. Requests a DNS-validated ACM certificate in the project’s region.
2. Waits for AWS to emit the CNAME validation records.
3. Prints them as a copy-paste table (name / value) for your DNS host.
4. Polls DescribeCertificate until the status is ISSUED (or returns immediately with --no-wait).
5. Writes the resulting ARN back into the matching domains[] entry in your config/*.ts, so CI reads it from committed source instead of juggling a secret per environment.

The command is idempotent by name set: re-running it for the same domain + SANs reuses the existing PENDING_VALIDATION / ISSUED certificate instead of stacking duplicates in ACM.

Subcommands

vk cert request

Option	Description	Default
-d, --domain <name>	Primary domain name, e.g. api.example.com (required)	—
-s, --san <name...>	Additional subject-alt names (repeatable)	none
-r, --region <region>	AWS region for ACM	base.region from vk.config.ts, else us-east-1
--no-wait	Print the validation records and the ARN, don’t wait for ISSUED	wait
-w, --write <file>	Config file to write the ARN into	auto-detected (see below)
--timeout <minutes>	Max minutes to wait for ISSUED	20

The region is deliberately not taken from the AWS CLI’s configured default: a certificate issued in the wrong region cannot be attached by API Gateway at deploy time. WebSocket custom domains use a regional certificate too, so the same region rule applies.

Writing the ARN back

Without --write, the command scans config/, the project root and src/config/ for a .ts file containing domain: '<name>'. If exactly one file matches, the enclosing object literal gets a certificateArn: '<arn>' property (replacing an existing one). If the match is ambiguous or missing, the ARN is printed for manual wiring — re-run with --write <file> to disambiguate.

// config/prod.ts — after `vk cert request --domain api.example.com`
domains: [
  {
    id: 'api',
    domain: 'api.example.com',
    certificateArn: 'arn:aws:acm:eu-west-1:123456789012:certificate/…',
  },
],

Examples

# Certificate for the API plus a preview alias, wait for ISSUED (up to 20 min)
vk cert request --domain api.example.com --san preview.api.example.com

# Print the CNAMEs and return immediately; deploy picks the cert up once issued
vk cert request --domain api.example.com --no-wait

# Pin the region and the config file explicitly
vk cert request --domain ws.example.com --region eu-west-1 --write config/prod.ts

A certificate that ends in FAILED or VALIDATION_TIMED_OUT aborts the command — check that the CNAME records are published and match exactly.

Do you need it?

Not necessarily. Since 0.0.2+, vk deploy’s pre-flight performs the same lookup / request for every external-DNS domain without a certificateArn, prints the same table, and attaches the domain on the first deploy after ACM reports ISSUED. vk cert request remains the recommended way to make CI independent of that lookup by pinning the ARN in source. See the Domain Intent for the full certificate-resolution rules.