Custom domains

Attach, change, check and remove custom domains, and verify domain ownership, from the terminal with gigadrive domains.

gigadrive domains manages the custom domains of an application and the domains your organization has verified. Use it to attach a hostname, read the DNS records to publish, and wait until the domain serves traffic.

Every command in the first group works on one application. It is the linked application, or the one you name with --app. See Project linking.

Command	What it does
`gigadrive domains list`	List the application's custom domains and their states
`gigadrive domains add`	Attach a hostname and print the DNS records to publish
`gigadrive domains update`	Change what a domain serves, or make it the primary URL
`gigadrive domains claim`	Move a hostname that another organization attached
`gigadrive domains inspect`	Print one domain, its problem, and the records still missing
`gigadrive domains check`	Check a domain's DNS records now instead of waiting
`gigadrive domains rm`	Remove a domain
`gigadrive domains owners ...`	List, add, verify and remove the organization's verified domains

Attach a domain

gigadrive domains add takes the hostname and prints the records to publish at your DNS provider.

gigadrive domains add shop.example.com

Add --wait to follow the domain until it is live. The command prints each state change and exits with an error if the domain fails or does not serve within --timeout minutes (default 10).

gigadrive domains add shop.example.com --wait

A domain serves your production deployment unless you choose another target.

Flag	Alias	Description
`--app`	`-a`	Operate on this application (overrides the linked application)
`--production`		Serve the production deployment (the default)
`--branch`		Serve the latest deployment of this branch ID
`--redirect-to`		Redirect every request to this hostname. Available on paid plans
`--status`		Redirect status code with `--redirect-to`: `301`, `302`, `307` or `308` (default `308`)
`--drop-path`		With `--redirect-to`, redirect to the root instead of keeping the path and query
`--wait`	`-w`	Wait until the domain serves traffic
`--timeout`		Minutes to wait with `--wait`, at least 1 (default 10)
`--json`		Print only the result as JSON on stdout; progress goes to stderr

--production, --branch and --redirect-to conflict with each other, and --status and --drop-path need --redirect-to. The command refuses these combinations before it calls the API.

An apex domain such as example.com needs an ALIAS, ANAME or flattened CNAME record. The command prints a reminder when the records include one.

Change a domain

gigadrive domains update takes a hostname or domain ID and at least one change.

gigadrive domains update shop.example.com --redirect-to www.example.com --status 301
gigadrive domains update www.example.com --production --primary

update accepts --app, --production, --branch, --redirect-to, --status, --drop-path and --json with the same meaning as add. --primary makes the domain the application's primary URL. Without a target flag or --primary, the command exits with Nothing to change.

Check and inspect a domain

gigadrive domains inspect prints the domain's state, any problem, and the DNS records that are still missing. gigadrive domains check asks Gigadrive Network to check the records right away and also accepts --wait and --timeout.

gigadrive domains inspect shop.example.com
gigadrive domains check shop.example.com --wait

A domain is in one of these states.

State	Meaning
verifying ownership	The platform is confirming that your organization owns the domain
waiting for DNS	The records you must publish are missing or different
issuing certificate	DNS is correct and the certificate is being issued
active	The domain serves traffic
needs attention	The domain serves traffic, but a check found a problem
failed	Setup stopped; the problem explains what to fix
suspended	The domain is over your plan's limit
removing	The domain is being removed

Troubleshooting custom domains covers the problem codes.

Move a domain from another organization

gigadrive domains claim moves a hostname that another organization attached to the application. Verify the domain for your organization first, and keep its TXT record published, because the claim checks it again. See Custom domains for the full sequence.

gigadrive domains claim shop.example.com

Remove a domain

gigadrive domains rm stops the domain from serving the application immediately. It asks for confirmation. Pass --yes (-y) to skip the prompt, which is required when the command does not run in a terminal.

gigadrive domains rm shop.example.com --yes

Verify domains for your organization

Verifying a domain once lets every application of the organization attach hostnames under it. The owners commands work on the organization from --org (-o), or on the linked project's organization.

gigadrive domains owners add example.com
gigadrive domains owners verify example.com
gigadrive domains owners list
gigadrive domains owners rm example.com --yes

owners add prints the TXT record to publish. Run owners verify after the record is live. owners rm takes --yes and asks for confirmation otherwise; remove the custom domains that rely on a verified domain first. owners list and owners add accept --json.