CLI
edge is a client of the HTTP API. Every command calls /v1 with your token for https://api.edge.deca-dev.com, and needs the scope shown for that command. To install it, see Install the CLI.
Global flags
| Flag | Meaning |
|---|---|
--profile NAME | Which profile to use (API host and sign-in). Default: the active profile |
--workspace ID_OR_SLUG | Workspace to act in. Omitted, Edge uses your organization's default workspace |
-o, --output FORMAT | table, json, jsonl, or tsv. See Output |
--fields a,b,c | Keep only these fields of each result |
--jq EXPR | Filter the JSON result with a jq expression. No separate jq install needed |
--raw | With --jq, print strings without quotes |
--pretty | Indent JSON |
--limit N | Return at most N items from a list |
--all | Follow pagination to the end of a list |
--yes | Skip the interactive "are you sure" prompt |
--dry-run | Print the request a command would send, then stop. Nothing changes |
--no-color | Plain output. NO_COLOR=1 does the same |
--debug | Log each request and response on stderr, with the token redacted |
Organization always comes from your token. There is no --organization flag.
Profiles
A profile is a set of connection settings: which API host to call and which sign-in to use. This environment's built-in profile is named edge.deca-dev.com.
edge profile list
edge profile use edge.deca-dev.com
edge profile showSign-ins are kept per profile in your system keychain. Settings live in ~/.config/edge/config.toml (Windows: %AppData%\edge\config.toml).
A project folder can pin its target with edge link, which writes .edge/project.json.
Where a setting is given in several places, the first one found wins: flag, environment variable, .edge/project.json, config file, built-in default.
Environment variables
| Variable | Meaning |
|---|---|
EDGE_CLIENT_ID, EDGE_CLIENT_SECRET | Machine credential for CI. The CLI exchanges it for a token on each run. See Use the CLI in CI |
EDGE_TOKEN | A personal access token (edge_pat_…) or an access token, used as is. Takes precedence over everything else |
EDGE_PROFILE | Same as --profile |
EDGE_WORKSPACE | Same as --workspace |
EDGE_OUTPUT | Same as --output |
EDGE_AGENT=1 | Output for a program: JSON, no color, no prompts |
EDGE_NO_UPDATE_CHECK=1 | Do not check for a newer version |
NO_COLOR | Plain status lines, without symbols |
EDGE_AGENT=1 is also assumed when the CLI detects it is running under a coding agent. An explicit --output always wins.
Output
| Format | What you get |
|---|---|
table | Aligned columns for reading. The default at a terminal |
json | The API response, unchanged. The default when output is piped or redirected |
jsonl | One JSON object per line. The default for streams such as logs tail when piped |
tsv | A header row, then one tab-separated row per item |
JSON output is the API's response body with nothing renamed, so the HTTP API and this page describe the same fields.
Progress messages, prompts, and errors go to stderr. Stdout carries only results.
Errors in json mode use the API's error envelope with the HTTP status and a suggestion added:
{"error":{"code":"forbidden","message":"missing scope deployment.promote","status":403,"hint":"run \"edge whoami\" to see your scopes"}}Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Other failure: network, server error |
2 | Usage error, including a confirmation that is required but no terminal to ask in |
3 | Not signed in, or the token expired or is for another audience |
4 | Forbidden: a missing scope, or a workspace outside your organization |
5 | Not found in this workspace |
6 | Conflict or validation failed |
7 | Rate limited, after retries |
8 | The deployment ended failed while the command was waiting |
Reads are retried on rate limits and server errors. Writes that create something are not.
Commands
Account
| Command | What it does |
|---|---|
edge login [--device] | Sign in through a browser on this machine (PKCE) and pick an organization. --device uses a one-time code on any device but cannot carry organization roles today |
edge logout | Remove the stored sign-in for the profile |
edge whoami | Show organization, workspace, scopes, and when the token expires |
edge token | Print your current short-lived access token, for use with curl |
edge tokens create | Create a personal access token: pick permissions and expiration, review, confirm |
edge tokens ls [--all] | List your tokens; --all lists the organization's (token.admin) |
edge tokens revoke ID | Revoke a token immediately |
edge workspaces ls | List your organization's workspaces |
Publishing
| Command | What it does | Live site changes? |
|---|---|---|
edge link | Save the distribution and folder for this project | No |
edge deploy [DIR] | Pack, upload, commit, and wait for a preview | No |
edge deploy --promote | The same, then promote | Yes |
edge deployments promote ID | Make a ready deployment live | Yes |
edge deployments promote ID --at TIME | Schedule that promote | Yes, at TIME |
edge deployments rollback | Put the previous deployment back | Yes |
edge distributions takedown ID --gone or --redirect URL | Answer 410, or a 302 to URL, on live hosts | Yes (now, or at --at) |
edge distributions restore ID | Lift a takedown | Yes (now, or at --at) |
edge redirects import DIST FILE --apply | Create a deployment with the imported redirects | No, until it is promoted |
edge deploy packs DIR as bundle.tar.gz with the files at the archive root, and leaves out .git, .edge, and macOS metadata files.
Workspaces
| Command | Scope |
|---|---|
edge workspaces ls | namespace.read |
Distributions
| Command | Scope |
|---|---|
edge distributions ls | distribution.read |
edge distributions get ID | distribution.read |
edge distributions create --slug SLUG --template T | distribution.write |
edge distributions update ID --config FILE | distribution.write |
edge distributions copy ID --slug NEW | distribution.write |
edge distributions rm ID --confirm-slug SLUG | distribution.destroy |
edge distributions slug-check SLUG | distribution.read |
edge distributions takedown ID (--gone | --redirect URL) [--at TIME] | deployment.promote |
edge distributions restore ID [--at TIME] | deployment.promote |
Deployments
| Command | Scope |
|---|---|
edge deployments ls | deployment.read |
edge deployments get ID | deployment.read |
edge deployments create [--from ID] | deployment.write |
edge deployments check | deployment.write |
edge deployments commit ID | deployment.write |
edge deployments promote ID [--at TIME [--tz ZONE]] | deployment.promote |
edge deployments rollback [--to ID] | deployment.promote |
edge schedules ls DIST [--status S] | deployment.read |
edge schedules cancel SCHEDULE | deployment.promote |
edge deployments diff FROM TO | deployment.read |
edge deploy [DIR] | deployment.write, deployment.read; --promote also needs deployment.promote |
edge deployments rollback restores an earlier ready deployment (by default the one before the live deployment) as a new deployment, waits for its preview, then promotes it. --preview-only stops before promoting.
--at takes RFC 3339 with an offset (2026-11-01T00:00:00+09:00), or a local time such as 2026-11-01 00:00 read in --tz (an IANA name such as Asia/Tokyo) or the computer's time zone. With --at, the command schedules the action and returns a schedule_id. See Schedule a launch and a takedown.
Checks
| Command | Scope |
|---|---|
edge distributions invalidate ID [--path P] | deployment.promote |
edge distributions redirect-check ID --path P | distribution.read |
edge redirects check DIST PATH [--deployment ID] | distribution.read |
edge redirects import DIST FILE [--format F] [--replace] [--apply] | distribution.write |
edge redirects export DIST [--format F] [--deployment ID] | distribution.read |
edge distributions header-check ID --path P | distribution.read |
edge distributions health ID | analytics.read |
edge redirects import is a dry run unless --apply is set. It exits with code 6 when the file has errors, after listing each one with its line number. The format comes from the file extension (.csv, .json, anything else is Netlify _redirects) unless --format is set. See Redirects.
Webhooks and hooks
| Command | Scope |
|---|---|
edge webhooks ls | webhook.read |
edge webhooks get ID | webhook.read |
edge webhooks create --url URL --event TYPE | webhook.write; form.* also needs form.forward and --yes |
edge webhooks update ID | webhook.write |
edge webhooks rm ID | webhook.write |
edge webhooks test ID | webhook.write |
edge webhooks rotate-secret ID | webhook.write |
edge webhooks deliveries ID | webhook.read |
edge webhooks redeliver ID DELIVERY | webhook.write |
edge hooks ls DISTRIBUTION | hook.read |
edge hooks get DISTRIBUTION HOOK | hook.read |
edge hooks create DISTRIBUTION --slug SLUG --preset PRESET | hook.write |
edge hooks update DISTRIBUTION HOOK | hook.write |
edge hooks rm DISTRIBUTION HOOK | hook.write |
edge hooks receipts DISTRIBUTION HOOK | hook.read |
edge hooks receipt DISTRIBUTION HOOK KEY | hook.read |
edge webhooks subscribes an HTTPS endpoint to Edge events. The signing secret is shown once. A subscription that includes form.* prints a summary and creates nothing until you confirm, or pass --yes. edge hooks receives another service's webhooks at /_hooks/{slug} on a distribution. Neither changes the live site by itself; a hook action of promote_latest or invalidate does, and only after the distribution is live. A hook action of enqueue, workflow_start or workflow_signal (set with --config) also needs queue.send or workflow.write. A wasm action runs one function runtime on this distribution after the 200; it needs hook.write and a function that already exists there.
Endpoints
| Command | Scope |
|---|---|
edge jobs ls DISTRIBUTION [--owner-kind K] [--status S] [--before NEXT] [--limit N] | function.read |
edge jobs ls lists background job runs, newest first. In a table it prints the next page's command on stderr; -o json returns the whole page, with next_before. Function runtimes themselves are managed through MCP.
Crons
| Command | Scope |
|---|---|
edge crons ls DISTRIBUTION | cron.read |
edge crons get CRON | cron.read |
edge crons create DISTRIBUTION --name N --schedule S (--function SCRIPT | --emit | --invalidate PATH | --promote-latest | --enqueue QUEUE | --start-workflow SCRIPT) | cron.write |
edge crons update CRON | cron.write |
edge crons rm CRON | cron.write |
edge crons trigger CRON | cron.write |
edge crons runs CRON [--status S] | cron.read |
edge crons check DISTRIBUTION --schedule S [--tz ZONE] | cron.read |
--tz takes an IANA name such as Asia/Tokyo; the default is UTC. A cron has exactly one target flag. --promote-latest and --invalidate change the live site every time the cron runs. edge crons update sends only the flags you set; --enabled false pauses the cron.
Queues
| Command | Scope |
|---|---|
edge queues ls DISTRIBUTION | queue.read |
edge queues get QUEUE | queue.read |
edge queues create DISTRIBUTION --name N (--function SCRIPT | --webhook URL) | queue.write |
edge queues update QUEUE | queue.write |
edge queues rm QUEUE | queue.write |
edge queues send QUEUE (--body JSON | --file FILE) | queue.send |
edge queues peek QUEUE [--status ready|leased|dead] [--bodies] | queue.read |
edge queues purge QUEUE --status ready|dead | queue.write |
edge queues redrive QUEUE [--message ID] | queue.write |
edge queues stats QUEUE | queue.read |
edge queues runs QUEUE [--status S] | queue.read |
create and update take --batch-size, --batch-wait, --concurrency, --max-attempts, --retention-days and --senders; update sends only the flags you set, and --paused true pauses the queue. send --file reads JSON Lines, one {"body": …, "delay_seconds"?, "idempotency_key"?} per line (- for stdin), and sends 100 per request. purge and rm ask before deleting unless --yes.
Workflows
| Command | Scope |
|---|---|
edge workflows start DISTRIBUTION --function SCRIPT [--input JSON] [--name N] [--key K] | workflow.write |
edge workflows ls DISTRIBUTION [--status S] | workflow.read |
edge workflows get RUN | workflow.read |
edge workflows signal RUN --name SIGNAL [--payload JSON] [--key K] | workflow.write |
edge workflows cancel RUN | workflow.write |
edge workflows retry RUN | workflow.write |
In a table, get prints the run's steps; -o json returns the whole run. cancel asks before cancelling unless --yes.
Access
| Command | Scope |
|---|---|
edge access show DISTRIBUTION | distribution.read |
edge access rules ls DISTRIBUTION | access.read |
edge access rules add DISTRIBUTION --kind KIND | access.write |
edge access rules rm RULE_ID | access.write |
edge access check DISTRIBUTION | access.read |
edge access revocations ls DISTRIBUTION | access.read |
edge access sessions revoke DISTRIBUTION | access.write |
edge access network ls [DISTRIBUTION] | access.read |
edge access network add (DISTRIBUTION | --all-sites) VALUE... | access.write |
edge access network rm RULE_ID | access.write |
edge access network check DISTRIBUTION [IP] | access.read |
edge access network mode DISTRIBUTION (enforce | login-fallback) | access.write |
edge access network ip | none |
--all signs everyone out. edge access network add allows by default; --block blocks, --country treats the values as country codes, and --mine adds this machine's address. edge access network ip and check without an IP read https://ip.edge.deca-dev.com/. See Access control.
Personal access tokens
| Command | Scope |
|---|---|
edge tokens ls | signed in; --all needs token.admin |
edge tokens create | signed in, not with a personal access token |
edge tokens revoke ID | signed in; another person's token needs token.admin |
Data objects, key-value and SQL storage, domains, analytics and logs, goals, analytics groups and funnels, properties and PII, and endpoints do not have dedicated commands yet. Until they do, call their routes from the HTTP API with edge api, which sends your token for you. The scope is the scope of the route you call:
edge api GET /v1/slugs/acme-marketing
edge api GET /v1/domains
edge api POST /v1/analytics --input query.jsonFunction runtimes, data-object history, grants, and private data objects have no HTTP route yet, so the CLI cannot manage them. Use an agent for those.
Utilities
| Command | What it does |
|---|---|
edge commands | List every command with its flags and scope (-o json for programs) |
edge completion bash|zsh|fish|powershell | Print a shell completion script |
edge version | Print the version |
edge upgrade | Check for a newer release and print the command that installs it |