Skip to content

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 ​

FlagMeaning
--profile NAMEWhich profile to use (API host and sign-in). Default: the active profile
--workspace ID_OR_SLUGWorkspace to act in. Omitted, Edge uses your organization's default workspace
-o, --output FORMATtable, json, jsonl, or tsv. See Output
--fields a,b,cKeep only these fields of each result
--jq EXPRFilter the JSON result with a jq expression. No separate jq install needed
--rawWith --jq, print strings without quotes
--prettyIndent JSON
--limit NReturn at most N items from a list
--allFollow pagination to the end of a list
--yesSkip the interactive "are you sure" prompt
--dry-runPrint the request a command would send, then stop. Nothing changes
--no-colorPlain output. NO_COLOR=1 does the same
--debugLog 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.

bash
edge profile list
edge profile use edge.deca-dev.com
edge profile show

Sign-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 ​

VariableMeaning
EDGE_CLIENT_ID, EDGE_CLIENT_SECRETMachine credential for CI. The CLI exchanges it for a token on each run. See Use the CLI in CI
EDGE_TOKENA personal access token (edge_pat_…) or an access token, used as is. Takes precedence over everything else
EDGE_PROFILESame as --profile
EDGE_WORKSPACESame as --workspace
EDGE_OUTPUTSame as --output
EDGE_AGENT=1Output for a program: JSON, no color, no prompts
EDGE_NO_UPDATE_CHECK=1Do not check for a newer version
NO_COLORPlain 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 ​

FormatWhat you get
tableAligned columns for reading. The default at a terminal
jsonThe API response, unchanged. The default when output is piped or redirected
jsonlOne JSON object per line. The default for streams such as logs tail when piped
tsvA 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:

json
{"error":{"code":"forbidden","message":"missing scope deployment.promote","status":403,"hint":"run \"edge whoami\" to see your scopes"}}

Exit codes ​

CodeMeaning
0Success
1Other failure: network, server error
2Usage error, including a confirmation that is required but no terminal to ask in
3Not signed in, or the token expired or is for another audience
4Forbidden: a missing scope, or a workspace outside your organization
5Not found in this workspace
6Conflict or validation failed
7Rate limited, after retries
8The 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 ​

CommandWhat 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 logoutRemove the stored sign-in for the profile
edge whoamiShow organization, workspace, scopes, and when the token expires
edge tokenPrint your current short-lived access token, for use with curl
edge tokens createCreate 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 IDRevoke a token immediately
edge workspaces lsList your organization's workspaces

Publishing ​

CommandWhat it doesLive site changes?
edge linkSave the distribution and folder for this projectNo
edge deploy [DIR]Pack, upload, commit, and wait for a previewNo
edge deploy --promoteThe same, then promoteYes
edge deployments promote IDMake a ready deployment liveYes
edge deployments promote ID --at TIMESchedule that promoteYes, at TIME
edge deployments rollbackPut the previous deployment backYes
edge distributions takedown ID --gone or --redirect URLAnswer 410, or a 302 to URL, on live hostsYes (now, or at --at)
edge distributions restore IDLift a takedownYes (now, or at --at)
edge redirects import DIST FILE --applyCreate a deployment with the imported redirectsNo, 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 ​

CommandScope
edge workspaces lsnamespace.read

Distributions ​

CommandScope
edge distributions lsdistribution.read
edge distributions get IDdistribution.read
edge distributions create --slug SLUG --template Tdistribution.write
edge distributions update ID --config FILEdistribution.write
edge distributions copy ID --slug NEWdistribution.write
edge distributions rm ID --confirm-slug SLUGdistribution.destroy
edge distributions slug-check SLUGdistribution.read
edge distributions takedown ID (--gone | --redirect URL) [--at TIME]deployment.promote
edge distributions restore ID [--at TIME]deployment.promote

Deployments ​

CommandScope
edge deployments lsdeployment.read
edge deployments get IDdeployment.read
edge deployments create [--from ID]deployment.write
edge deployments checkdeployment.write
edge deployments commit IDdeployment.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 SCHEDULEdeployment.promote
edge deployments diff FROM TOdeployment.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 ​

CommandScope
edge distributions invalidate ID [--path P]deployment.promote
edge distributions redirect-check ID --path Pdistribution.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 Pdistribution.read
edge distributions health IDanalytics.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 ​

CommandScope
edge webhooks lswebhook.read
edge webhooks get IDwebhook.read
edge webhooks create --url URL --event TYPEwebhook.write; form.* also needs form.forward and --yes
edge webhooks update IDwebhook.write
edge webhooks rm IDwebhook.write
edge webhooks test IDwebhook.write
edge webhooks rotate-secret IDwebhook.write
edge webhooks deliveries IDwebhook.read
edge webhooks redeliver ID DELIVERYwebhook.write
edge hooks ls DISTRIBUTIONhook.read
edge hooks get DISTRIBUTION HOOKhook.read
edge hooks create DISTRIBUTION --slug SLUG --preset PRESEThook.write
edge hooks update DISTRIBUTION HOOKhook.write
edge hooks rm DISTRIBUTION HOOKhook.write
edge hooks receipts DISTRIBUTION HOOKhook.read
edge hooks receipt DISTRIBUTION HOOK KEYhook.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 ​

CommandScope
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 ​

CommandScope
edge crons ls DISTRIBUTIONcron.read
edge crons get CRONcron.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 CRONcron.write
edge crons rm CRONcron.write
edge crons trigger CRONcron.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 ​

CommandScope
edge queues ls DISTRIBUTIONqueue.read
edge queues get QUEUEqueue.read
edge queues create DISTRIBUTION --name N (--function SCRIPT | --webhook URL)queue.write
edge queues update QUEUEqueue.write
edge queues rm QUEUEqueue.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|deadqueue.write
edge queues redrive QUEUE [--message ID]queue.write
edge queues stats QUEUEqueue.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 ​

CommandScope
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 RUNworkflow.read
edge workflows signal RUN --name SIGNAL [--payload JSON] [--key K]workflow.write
edge workflows cancel RUNworkflow.write
edge workflows retry RUNworkflow.write

In a table, get prints the run's steps; -o json returns the whole run. cancel asks before cancelling unless --yes.

Access ​

CommandScope
edge access show DISTRIBUTIONdistribution.read
edge access rules ls DISTRIBUTIONaccess.read
edge access rules add DISTRIBUTION --kind KINDaccess.write
edge access rules rm RULE_IDaccess.write
edge access check DISTRIBUTIONaccess.read
edge access revocations ls DISTRIBUTIONaccess.read
edge access sessions revoke DISTRIBUTIONaccess.write
edge access network ls [DISTRIBUTION]access.read
edge access network add (DISTRIBUTION | --all-sites) VALUE...access.write
edge access network rm RULE_IDaccess.write
edge access network check DISTRIBUTION [IP]access.read
edge access network mode DISTRIBUTION (enforce | login-fallback)access.write
edge access network ipnone

--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 ​

CommandScope
edge tokens lssigned in; --all needs token.admin
edge tokens createsigned in, not with a personal access token
edge tokens revoke IDsigned 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:

bash
edge api GET /v1/slugs/acme-marketing
edge api GET /v1/domains
edge api POST /v1/analytics --input query.json

Function 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 ​

CommandWhat it does
edge commandsList every command with its flags and scope (-o json for programs)
edge completion bash|zsh|fish|powershellPrint a shell completion script
edge versionPrint the version
edge upgradeCheck for a newer release and print the command that installs it

See also ​