domain add

writes--dry-run

Registers a domain and, when an application is named, points it there in the same call.

The certificate is issued once DNS resolves to the record domain dns prints. There is nothing else to configure and nothing to renew.

Usage

outplane domain add <HOST> [flags]

Arguments

Argument	Type	Description
`HOST`	`string`	The domain, such as app.example.com. Required.

Flag	Type	Description
`--path`	`string`	Which route on the host, defaulting to the root. Needed only when the host carries several.
`--app`	`string`	Application to point it at.
`--port`	`int`	Which of the application's ports. Optional when it serves one.

Output

Field	Type	Description
`id`	`string \| null`
`host`	`string`
`path`	`string`	Trailing slashes are stripped; the root is /.
`app`	`string \| null`	Null while the route points nowhere.
`appId`	`string \| null`
`portId`	`string \| null`	The port record the route binds to.
`ssl`	`bool`	Always true: a certificate is issued for every custom domain.
`url`	`string \| null`	The address the route answers on.
`changed`	`bool`

Examples

A domain for an application

outplane domain add app.example.com --app checkout --port 3000

Register the host first, point it later

outplane domain add app.example.com

A second route on the same host

outplane domain add example.com --path /api --app api01 --port 8080

Check the request without registering anything

outplane domain add app.example.com --dry-run --json

{
  "changed": false,
  "host": "app.example.com",
  "path": "/"
}

What to Know

The host and the path together have to be unique. The same host with a different path is a second route and is allowed.
/.well-known/acme-challenge is refused: the platform answers certificate challenges there, and a route on it would stop the certificate renewing.
A TCP port cannot take a domain, and neither can an application that has never deployed successfully.
Adding does not make it work. DNS has to point at the record this prints, and the certificate follows once it resolves.
How many domains a team may have is a plan limit, so exceeding it is exit 7.

Errors

Beyond 0 for success, this command exits with:

Exit	Kind	Meaning
`2`	`usage`	Invalid arguments, unknown flag, or client-side validation failure.
`3`	`auth`	Not authenticated, token revoked or expired, or forbidden for this team.
`5`	`not_found`	The named resource does not exist, or is not visible to this credential.
`7`	`quota`	Plan limit reached or payment required. Not a rate limit; retrying will not help.
`8`	`upstream`	The Out Plane API returned a server error.

The code on the error object is one of domain.host_required, domain.host_invalid, domain.path_invalid, domain.path_reserved, domain.app_required, domain.port_not_found, domain.no_ports, quota.limit_reached, app.not_found. Branch on that, or on the exit status. The message is prose and changes.