Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.edgespark.dev/llms.txt

Use this file to discover all available pages before exploring further.

Every EdgeSpark project ships behind a platform-managed default URL like your-project.edgespark.app. To serve your own purchased hostname instead, use the edgespark domain family of CLI commands. The CLI prints exactly the DNS records you need; the platform handles ownership verification, EdgeSpark routing, and TLS certificate issuance. You stay in your project directory the whole time. Each command resolves the project from edgespark.toml and your authenticated CLI session.

​
Add a domain

edgespark domain add app.example.com
The CLI registers the hostname against your project and returns the DNS records to publish. The actual record names and values are computed per project — copy them verbatim from the CLI output. A subdomain looks like: 
Domain added

Hostname: app.example.com
Status:   pending

DNS records
  CNAME  app.example.com -> custom.edgespark.app
        Purpose: routing
  TXT    _edgespark-verify-<scoped>.app.example.com -> edgespark-domain-verification=<token>
        Purpose: ownership

User action required
  1. Add every DNS record above at the domain's DNS provider.
     For apex/root domains, use @ if your DNS provider asks for a host/name.
  2. Wait for DNS propagation; EdgeSpark certificate issuance is automatic.
  3. Run `edgespark domain verify app.example.com` to wait for activation.
Publish every record in the list — the CNAME makes traffic flow, and the TXT is what EdgeSpark uses to prove the domain belongs to you. The <scoped> segment of the TXT name is derived from your project ID, so two projects can never claim the same hostname with conflicting tokens. If your DNS provider supports domain-connect, add may also print a Setup URL you can open to add the records with one click instead of copy-pasting.
EdgeSpark uses a TXT ownership challenge — there is no nameserver delegation. Your existing DNS provider stays in charge.

​
Verify activation

After publishing the DNS records, wait for the domain to flip active: 
edgespark domain verify app.example.com
The command polls every 15 seconds until the domain is active or the timeout is reached. Default timeout is 15 minutes; raise it for slow DNS or busy certificate authorities: 
edgespark domain verify app.example.com --timeout 30m
--timeout accepts ms, s, m, h units (e.g. 90s, 5m, 1h). When activation succeeds: 
Domain verified and active

Hostname: app.example.com
Status:   active
URL:      https://app.example.com
If the timeout elapses before activation, the CLI prints the current status, repeats any DNS records still missing, and exits 0 so you can re-run verify later. The domain is not lost — it stays registered on the project.

​
Inspect a domain

status is a one-shot read of where a domain stands. It does not poll: 
edgespark domain status app.example.com
Output includes the activation Status, the platform’s view of routing health (EdgeSpark routing), the TLS certificate state (SSL), any warnings, and the DNS records still pending if setup is incomplete. 
Hostname:          app.example.com
Status:            active
EdgeSpark routing: active
SSL:               active
URL:               https://app.example.com
Status is the high-level activation flag. EdgeSpark routing and SSL are independent, finer-grained strings sourced from the platform’s CDN integration — when a domain is stuck in pending, look at those two fields to tell DNS-side problems apart from TLS-issuance problems. Use status for spot checks; use verify when you want the CLI to wait.

​
List domains

edgespark domain list
Prints a table of every custom domain on the current project with its status and live URL. Use this from CI or scripts to confirm what is wired up.

​
Remove a domain

edgespark domain remove app.example.com
Detaches the hostname from the project. The CLI returns the post-removal status; depending on your DNS provider, you may also want to delete the CNAME and TXT records at the source.

​
Domain status values

The high-level Status field can take five values:
StatusMeaningWhat to do
pendingRegistered; ownership / routing / TLS not yet all confirmedConfirm the records are published, then edgespark domain verify. Check EdgeSpark routing and SSL to see which step is still in flight.
activeLive and serving traffic with a valid certificateVisit the URL — traffic is on.
failedSetup hit a permanent errorRead the warning in edgespark domain status (and the error_message field), fix the underlying issue (typo in records, CAA blocking issuance), and re-run edgespark domain verify.
removingDetachment is in progress on the platform sideWait. domain status will flip to removed.
removedDetachment completedThe hostname is free for re-add via edgespark domain add.
status and verify also surface a free-form error_message field when the platform has a specific reason for a non-active state.

​
Apex versus subdomain

Both shapes work — the CLI prints the right records for each:
  • Subdomain (app.example.com) — a CNAME record where the host is the full hostname.
  • Apex (example.com) — the same CNAME record, but with @ as the host. Your DNS provider must support CNAME flattening at the apex — Cloudflare, Route 53, DNSimple, Vercel DNS, and others do; some legacy registrars do not. If yours does not support flattening, choose a subdomain instead.
When in doubt, copy the records the CLI prints verbatim — they are what the platform expects.

​
Troubleshooting

SymptomLikely causeFix
pending after publishing recordsDNS has not propagated, or an extra record is shadowing yoursdig app.example.com and dig TXT _edgespark-verify-<scoped>.app.example.com to confirm what the world sees.
pending with EdgeSpark routing: active but SSL not activeCertificate issuance is in flight or blockedCheck for a restrictive CAA record on the apex; either add the EdgeSpark CA or remove the restrictive entry. Otherwise wait.
failed with a CAA mention in error_messageExisting CAA record blocks the certificate authority EdgeSpark usesUpdate the CAA record set, then edgespark domain verify.
verify exits with status still pending after 15 minutesSlow registrar or large TTLRe-run with --timeout 30m (or longer). The domain stays attached between attempts.
Project ID required (exit code 2)Command was run outside a project directory or edgespark.toml is missingcd into the project, or set EDGESPARK_PROJECT_ID for one-off runs.
For platform-wide naming and quota limits, see platform limits.

​
See also

Deploy your project

Ship a build and learn the default project URL the platform issues.

Environments

The current single-environment model and how custom domains fit it.
Last modified on April 30, 2026