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:
EDGE_TOKEN=edge_pat_… # secret: never print it
EDGE_PROFILE=edge.deca-dev.comWhen 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
curl -fsSL https://cli.edge.deca-dev.com/install.sh | EDGE_VERSION=0.1.6 shPin the version so a new release cannot change your pipeline's behavior unannounced. EDGE_INSTALL_DIR chooses where the binary goes.
3. Publish
edge deploy dist \
--distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 \
--wait --timeout 10m \
--output json > deployment.json
jq -r .preview_url deployment.json--distributionnames the target explicitly. A committed.edge/project.jsonfromedge linkworks too.--waitblocks until the deployment isreadyorfailed, so the step's result is the deployment's result.--output jsonwrites 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:
| Exit | Means | Typical pipeline response |
|---|---|---|
0 | Success | Continue |
3 | Token missing, expired, revoked, or for another environment | Replace the EDGE_TOKEN secret; check EDGE_PROFILE |
4 | The token lacks a scope | Use a token with that scope |
6 | Conflict or validation failed | Fix the input; retrying will not help |
7 | Rate limited after retries | Retry the job later |
8 | Deployment ended failed | Read the deployment's error with edge deployments get |
The full list is in the CLI reference.