CLI

The dply-edge CLI drives the dply HTTP API from your terminal. Link a repository to an app, then deploy, roll back, promote previews, manage domains and environment variables, tail request logs, query D1 databases, and route notifications without opening the dashboard. Use it on your own machine and in CI.

The CLI calls the same endpoints as the HTTP API, so every command is limited by the abilities on your token and by your role in the organization.

Install#

The CLI is served by dply itself, not by the npm registry. You need Node.js 18 or later and npm. The installer downloads the package from https://edge.dply.io/cli/dply-cli.tgz and installs it globally with npm install -g.

curl -fsSL https://edge.dply.io/cli/install.sh | bash -s -- --login

--login runs dply-edge login when the install finishes. The installer accepts these options:

Check which version dply is serving, and which version you have:

curl -fsSL https://edge.dply.io/cli/version.json
dply-edge --version

Update#

New commands ship with the platform, so updating means installing whatever build dply is serving right now:

dply-edge update            # install the build dply is serving
dply-edge update --check    # report only; exits 1 when your build differs
dply-edge update --json     # {installed, serving, up_to_date, base_url}
dply-edge update --force    # reinstall even when up to date

The check compares your build with the served build for equality, not "newer than". If the served build is rolled back, dply-edge update rolls your CLI back too. If the global install fails with a permission error, re-run with sudo or use the install script again.

Sign in#

dply-edge login uses a device flow, the same pattern as the GitHub and Stripe CLIs. You approve the terminal in your browser. You never paste a password or token into the terminal.

dply-edge login

1. The CLI asks dply for a code pair and prints a URL and an eight-character code in the form ABCD-EFGH. It tries to open the URL in your browser.
2. In the browser, sign in if you need to. Confirm that the code matches the one in your terminal.
3. Choose the organization the CLI should act in, then select the scopes (abilities) to grant.
4. Choose Approve. The terminal saves the token and opens the interactive shell.

The code expires after 15 minutes. If you deny the request, or the code expires, the CLI exits with code 2 and you run dply-edge login again. Press Ctrl+C to cancel.

Scopes you can grant#

The approval page only offers scopes your organization role allows. The server applies the same limit when it issues the token, so a modified request can't exceed it.

See Roles & permissions for what each role can do. The HTTP API page describes each ability.

Tokens issued through dply-edge login are named dply-edge CLI and don't expire. They stop working when someone revokes them, or when you leave the organization.

Add more scopes later#

If a command fails with 403 Forbidden, your token doesn't carry the ability that command needs. Approve a new token with more scopes:

dply-edge auth refresh

dply-edge refresh and dply-edge account refresh do the same thing. The CLI shows the scopes that were added and removed, then revokes the previous CLI session. Pass --keep-old to keep the old session, --no-open to skip opening the browser, or --base-url to refresh against another host.

Sign in from CI#

In CI, create an API token under Profile → API keys (see HTTP API) and pass it with --token:

dply-edge login --token "$DPLY_TOKEN" --base-url https://edge.dply.io --no-shell
dply-edge deploy --site "$DPLY_EDGE_SITE" --wait

A GitHub Actions workflow:

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: curl -fsSL https://edge.dply.io/cli/install.sh | bash
      - run: dply-edge login --token "${{ secrets.DPLY_TOKEN }}" --base-url https://edge.dply.io --no-shell
      - run: dply-edge deploy --wait --commit "${{ github.sha }}"
        env:
          DPLY_EDGE_SITE: ${{ vars.DPLY_EDGE_SITE }}

The token needs edge.read and edge.deploy. Either commit .dply/site.json or set DPLY_EDGE_SITE. --commit deploys the exact commit that triggered the workflow; leave it out to deploy the head of the app's branch. Profile → CLI in the dashboard shows the same workflow with your instance's URLs filled in.

Verify your setup#

dply-edge whoami     # user, organization, role, token abilities, linked site
dply-edge sites      # apps this token can see

Link a folder to an app#

Create the app in the dashboard first. The CLI can't create apps. Then, from your repository:

dply-edge link              # pick from a list
dply-edge link <site-id>    # or link by id

dply-edge link writes .dply/site.json in the current folder. Commands that act on one app look for that file in the current folder and its parents. The file also records which dply host the app lives on, so a linked repository keeps deploying to the right place after you switch hosts.

Every app-scoped command chooses its app in this order:

1. The --site <id> flag.
2. The DPLY_EDGE_SITE environment variable.
3. The linked folder (.dply/site.json).

Deploy#

dply-edge deploy --wait

dply-edge deploy deploys the linked app, or the app that --site or DPLY_EDGE_SITE names. It's the same as dply-edge edge deploy. If the folder isn't linked, the command exits with code 2. If an older CLI linked the folder to a site type dply no longer hosts, dply-edge deploy asks you to re-link it.

Command reference#

Run dply-edge help for a summary, dply-edge ls for a flat list of commands, or dply-edge edge --help for the app commands. Every two-word command also works in colon form: dply-edge edge:status is the same as dply-edge edge status.

Commands that print tables accept --json where noted.

Account#

Reading needs account.read and revoking needs account.write.

Hosts (dply-edge use)#

A token works only on the dply host that issued it. The CLI stores a separate sign-in for each host and lets you switch between them:

Hosts are keyed by hostname. dply-edge login --base-url <url> adds a host without removing the others.

Apps#

App commands (dply-edge edge)#

Each of these accepts --site <id>.

env push reads KEY=value lines. It supports double-quoted values (with \n and \t escapes), single-quoted literal values, export prefixes, and # comments. It skips keys that aren't uppercase letters, digits, and underscores.

Tail logs#

dply-edge edge logs

Prints request logs as they arrive: time, method, status, duration, cache status, and path. Press Ctrl+C to stop.

See Logs for what gets recorded.

An app's databases#

These commands work on the linked app's Postgres, MySQL and MongoDB databases. <db> is the database's name or ID. See Databases.

The query is read-only, but it returns your app's data, so it needs edge.write. Creating, attaching, resizing and deleting a database stay in the dashboard.

Databases and queues#

These commands work on the organization's D1 databases and queues. See Edge SQL (D1) and Queues.

dply-edge kv shares the key-value API's limit of 60 calls a minute per organization. It's for seeding and inspecting keys, not for app traffic. Every dply-edge kv command except list also needs you to be an organization owner or admin.

Notifications#

Routing links a channel, an event, and the app it fires for. See Notification channels.

dply-edge notify is an alias. --channel (or -c) accepts a channel id or part of its label. --site (or -s) accepts an app id or name. In a terminal, the CLI shows a picker when either is ambiguous.

Billing#

Available to organization owners and admins, with billing.read.

See Usage & metering and Invoices & taxes.

Interactive mode#

Run dply-edge with no arguments in a terminal, or dply-edge shell, to open an interactive shell with tab completion. dply-edge menu (or dply-edge m) shows numbered menus, so you don't have to remember command names.

Shortcuts: me and who run whoami, orgs runs account orgs, bill runs billing show, and r runs refresh.

Configuration#

Environment variables#

Exit codes#

Errors go to standard error, prefixed with dply:. On a 403, the CLI suggests dply-edge auth refresh.

Revoke CLI sessions#

Each approved device appears as a session. To revoke one:

• From the terminal, run dply-edge account sessions, then dply-edge account revoke <session-id>.
• In the dashboard, open Profile → CLI. Under CLI authentications, choose Revoke next to the session. Only organization owners and admins can see this list.

Revoking a session invalidates its token right away. That machine must run dply-edge login again. Removing someone from the organization also stops every token they hold for it.

Related#

• HTTP API
• API reference
• Deployments
• MCP server