Skip to content

Use the CLI in CI ​

This page covers any CI system. For ready-made workflows, see Publish from GitHub Actions. If you have not used the CLI interactively, start with Install the CLI.

1. Provide a token ​

A pipeline cannot open a browser, so it does not run edge login. Create a personal access token with only the permissions the pipeline needs, and store it as a CI secret named EDGE_TOKEN:

bash
EDGE_TOKEN=edge_pat_…   # secret: never print it
EDGE_PROFILE=edge.deca-dev.com

When EDGE_TOKEN is set, the CLI uses it and ignores any stored sign-in. EDGE_PROFILE makes the target environment explicit.

The token decides what the pipeline can do. One that publishes previews needs deployment.read and deployment.write; one that also promotes needs deployment.promote. See Permission scopes.

If your administrator issued a machine credential instead (a client ID and secret), set EDGE_CLIENT_ID and EDGE_CLIENT_SECRET and leave EDGE_TOKEN unset; the CLI exchanges them for a token on each run.

2. Install a pinned version ​

bash
curl -fsSL https://cli.edge.deca-dev.com/install.sh | EDGE_VERSION=0.1.6 sh

Pin the version so a new release cannot change your pipeline's behavior unannounced. EDGE_INSTALL_DIR chooses where the binary goes.

3. Publish ​

bash
edge deploy dist \
  --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 \
  --wait --timeout 10m \
  --output json > deployment.json
jq -r .preview_url deployment.json
  • --distribution names the target explicitly. A committed .edge/project.json from edge link works too.
  • --wait blocks until the deployment is ready or failed, so the step's result is the deployment's result.
  • --output json writes the finished deployment (id, status, preview_url, …) as JSON on stdout. Progress and errors go to stderr, so stdout stays parseable.

This publishes a preview only. The live site does not change. To promote in the same job, add --promote. Many teams keep promotion as a separate, manually approved step, so a person looks at the preview first; then run edge deployments promote ID --wait with the id from deployment.json.

4. Handle failures ​

The CLI never prompts when there is no terminal. A command that needs confirmation fails with exit code 2 and names the flag to pass, such as --confirm-slug acme-marketing for edge distributions rm.

Branch on the exit code rather than on message text:

ExitMeansTypical pipeline response
0SuccessContinue
3Token missing, expired, revoked, or for another environmentReplace the EDGE_TOKEN secret; check EDGE_PROFILE
4The token lacks a scopeUse a token with that scope
6Conflict or validation failedFix the input; retrying will not help
7Rate limited after retriesRetry the job later
8Deployment ended failedRead the deployment's error with edge deployments get

The full list is in the CLI reference.

Next ​