Edgio

CLI

This guide shows you everything you can do with the Edgio command line interface.
By default, Edgio CLI v5.1.0+ collects usage and error reporting information to help improve our products. However, it omits personally identifiable information. Learn how to opt-out.

Installation

To install, or upgrade to the latest, Edgio CLI run
Bash
1npm i -g @edgio/cli@latest
Or with yarn
Bash
1yarn global add @edgio/cli@latest

Upgrade Project to Latest Version

If you already have a project running on Edgio and you want to update packages to the most recent release of @edgio, simply run:
Bash
1edgio use latest
Before deploying your property, verify that all functionality, including request/response data, is as expected.

Commands

build

Creates a build of your app optimized for production.

Options

NameDescription
--skipFramework, -sSkips the framework (Next.js, Vue, Angular, etc..) build and simply rebundles your router
--disablePermanentAssetsSet this to true to suppress errors like “Immutable file (…) content was changed” during deployment.
--includeSourcesIncludes all non-gitignored source files in the bundle uploaded to Edgio. This can be helpful when debugging, especially when working with Edgio support. You can limit the files that are uploaded using the sources configuration in edgio.config.js.

Example

Bash
1edgio build

cache-clear

Clears the cache. If neither --path nor --surrogate-key is specified, the entire cache for the specified environment will be cleared.

Options

NameDescription
--team
  • Edgio CLI version 7.2.2 or higher: Deprecated. Use --organization instead.
  • Edgio CLI version 7.2.1 or lower: (Required) The organization name
--organizationEdgio CLI version 7.2.2 or higher: (Required) The organization name
--property(Required) The property name
--environment(Required) The environment name
--path, -pA path to clear. Use ”*” as a wildcard
--surrogate-key, -sClears all responses assigned to the specified surrogate key (cache tag)

Example

Bash
1edgio cache-clear --organization=my-organization --property=my-property --environment=production --path=/p/*

completion

Creates a script that provides autocompletion for Edgio CLI commands that can be installed in your shell.

Example

Bash
1edgio completion

Using ZSH

Bash
1edgio completion >> ~/.zshrc

Using BASH

Bash
1edgio completion >> ~/.bashrc

config

Sets configuration options for this property.

set-analytics

CommandDescription
set-analyticsSet this to false to prevent sending usage data. Optionally, you may set the environment variable EDGIO_DISABLE_ANALYTICS=1.

Example

Bash
1edgio config set-analytics false

set-backend

CommandDescription
set-backend <backend>Sets the --domainOrIp, -d and/or --hostHeader, -h to the existing <backend>
This command must be called with <backend> already existing in the edgio.config.js file. If <backend> does not exist, an error will be thrown.

Example

Bash
1edgio config set-backend origin -d docs.edg.io

curl

Uses curl to make a request to the specified URL, highlighting Edgio-specific telemetry information. See Response for more information around response headers and telemetry values.

Options

NameDescription
--jsonOutputs the response variables in JSON format, including telemetry data, headers, cookies, and the body (if using --show-body). Defaults to false
--debugRun in verbose mode. This has no effect when using with --json option.
--save-bodyWrites the response body to a temporary file path which is set in the output. This has no effect when using with --json option.
--show-bodyPrints the response body in the output. Defaults to false.
--max-body-lengthMaximum body length that will be returned. Defaults to 1024.
--curl-bin-pathAllows overriding path to curl bin. This is only required when curl is not in $PATH or you need to run different versions of curl.
--highlight-headers, --hlhThis will highlight matching headers. This has no effect when using with --json option. Defaults to ["x-0-","cache-control"].

Example

Bash
1➜ ~ edgio curl https://docs.edg.io
2
3URL : https://docs.edg.io/ 🔗
4From: 127.0.0.1:53857 🖥️
5To : 64.12.0.86:443 🌎
6
7HTTP/2 200
8Response Headers
9 accept-ranges: bytes
10 age: 3933
11 cache-control: private, no-cache, no-store, must-revalidate
12 content-length: 230488
13 content-security-policy: default-src 'self'; style-src 'unsafe-inline' 'self' fonts.googleapis.com cdn.jsdelivr.net; font-src fonts.gstatic.com; img-src 'self' www.google-analytics.com www.google.com analytics.twitter.com www.facebook.com px.ads.linkedin.com *.intercomcdn.com tr.lfeeder.com data: *.moovweb.net edgeio.whitecdn.com; frame-src www.youtube.com youtu.be player.vimeo.com; script-src 'unsafe-inline' 'self' 'unsafe-eval' *.clarity.ms *.google-analytics.com *.googletagmanager.com *.hotjar.com cdn.jsdelivr.net cdn.segment.com cdn4.mxpnl.com connect.facebook.net googletagmanager.com js.intercomcdn.com player.vimeo.com px4.ads.linkedin.com s.adroll.com sc.lfeeder.com snap.licdn.com widget.intercom.io www.google-analytics.com www.googletagmanager.com www.youtube.com; base-uri 'self'; frame-ancestors 'self'; media-src www.youtube.com; connect-src *.algolia.net *.algolianet.com *.clarity.ms *.doubleclick.net *.ecdns.net *.edg.io *.edgio-perma.link *.edgio.link *.github.io *.google-analytics.com *.googletagmanager.com *.intercom.io *.intercomassets.com *.intercomcdn.com *.layer0.co *.segment.com *.segment.io *.vimeo.com analytics.google.com googletagmanager.com vimeo.com
14 content-type: text/html
15 date: Thu, 27 Jul 2023 14:45:10 GMT
16 etag: "6057eecb93e2cfa6f6e09ba988ed960f"
17 last-modified: Thu, 27 Jul 2023 13:13:11 GMT
18 server: ECAcc (dcd/7D26)
19 server-timing: edgio_cache;desc=TCP_HIT,edgio_pop;desc=dcd,edgio_country;desc=US
20 strict-transport-security: max-age=31536000; includeSubDomains; preload
21 x-amz-id-2: O1cEPkkwP2jmKwLm+iAShlEH5Fx8bdGKB1fdqmiBgYFNihPNlYusXJMiPooPyEvQyFvhjBoS/LI=
22 x-amz-meta-contentmd5: YFfuy5Piz6b24JupiO2WDw==
23 x-amz-request-id: VP26DEYJF5M5Y2E2
24 x-amz-server-side-encryption: AES256
25 x-cache: HIT
26 x-ec-cache: TCP_HIT from ECAcc (dcd/7D26)
27 x-ec-cache-key: //http/801C2D83/edgio_static/110/edgio-community-docs-edg-io-main-110/next_prerendered_pages/index.html:/hs-1649885743736125473.html
28 x-ec-cache-state: max-age=31536000 (1y); cache-ts=1690465177 (Thu, 27 Jul 2023 13:39:37 GMT); cache-age=3933 (1h 5m 33s); remaining-ttl=31532067 (364d 22h 54m 27s); expires-delta=none
29 x-ec-check-cacheable: YES
30 x-edg-mr: 19:0;19:2;19:3;19:13;
31 x-edg-version: 110 19 12 7.0.23 2023-07-27T13:12:34Z bc3550f5-75c6-4f25-9b49-a407d6a11b15
32 x-sw-cache-control: max-age=3600
33 x-xss-protection: 1; mode=block
34
35
36 DNS Lookup TCP Connection TLS Handshake Server Processing Content Transfer
37[ 294ms | 27ms | 95ms | 28ms | 56ms ]
38 | | | | |
39 namelookup:294ms | | | |
40 connect:322ms | | |
41 pretransfer:417ms | |
42 starttransfer:445ms |
43 total:501ms
44
45Response Body
46 Disabled. To enable use EDGIO_CURL_SAVE_BODY=true or EDGIO_CURL_SHOW_BODY=true

deploy

Builds and deploys your property on Edgio.

Parameters

NameDescription
teamThe name of the organization under which the property will be deployed. The property will be deployed to your private space will be used if omitted.

Options

NameDescription
--team, -t
  • Edgio CLI version 7.2.2 or higher: Deprecated. Use --organization instead.
  • Edgio CLI version 7.2.1 or lower: The name of the organization under which the property will be deployed. If omitted, the team config in edgio.config.js will be used, or deployed to your private space if omitted.
--organizationEdgio CLI version 7.2.2 or higher: The name of the organization under which the property will be deployed. If omitted, the team config in edgio.config.js will be used, or deployed to your private space if omitted.
--propertyThe name of the property to deploy. By default the name field in edgio.config.js or package.json is used.
--environment, -eThe environment to deploy to. By default the default environment is used.
--branch, -bThe name of the source control branch. This is automatically set when using Git.
--skipFramework, --sfSkips running the framework build and uses the previous build instead.
--skipBuildSkips running the edgio build command, including the framework build, and uses the previous build instead.
--tokenAuthenticates using a deploy token rather than your user credentials. Use this option when deploying from CI. Alternatively, you can also specify the deploy token by setting the EDGIO_DEPLOY_TOKEN environment variable.
--includeSourcesIncludes all non-gitignored source files in the bundle uploaded to Edgio. This can be helpful when debugging, especially when working with Edgio support. You can limit the files that are uploaded using the sources configuration in edgio.config.js.
--disablePermanentAssetsSet this to true to suppress errors like “Immutable file (…) content was changed” during deployment.

Getting Information about the Deployment

The deploy command writes a file called .edgio/deployment-manifest.json, which contains the following information:
JavaScript
1{
2 "number": /* the deployment number */,
3 "url": /* the permalink URL for the deployment */,
4 "environment": {
5 "url": /* The edge URL for the deployment */,
6 "name": /* The name of the environment that was deployed to */
7 }
8}

Example

Bash
1edgio deploy my-organization --environment=production

dev

Runs your project in development mode, simulating the Edgio cloud environment. This command is a simplified version of edgio run, with only the —cache option being supported.

Options

NameDescription
--cache, -cEnables caching during local development so that you can test the caching logic in your router.

Example

Bash
1edgio dev

docs

Open the Edgio documentation in your browser.

Example

Bash
1edgio docs

env

Manage deployed property’s environments and environment variables.

Parameters

NameDescription
pull <path-to-env-file>Copy non-secret environment variables from an environment to a local .env file.

Options

NameDescription
--team, -t
  • Edgio CLI version 7.2.2 or higher: Deprecated. Use --organization instead.
  • Edgio CLI version 7.2.1 or lower: The name of the organization under which the property belongs. Uses private space if omitted.
--organizationEdgio CLI version 7.2.2 or higher: The name of the organization under which the property belongs. Uses private space if omitted.
--propertyThe property to pull variables from. Uses package.json name property if omitted.
--environment, -eEnvironment to pull variables from. Uses default environment if omitted.
--pathPath to your site’s root directory. Uses current directory by default.

Example

Bash
1edgio env pull .env.local --organization my-organization --property my-property --environment production

init

Run this command from the root directory of your web application or website to add all packages and files required to deploy your app on Edgio.
If you are not using the latest version of Edgio, then you must specify the --edgioVersion latest option when running this command.

Example

Bash
1edgio init

Options

NameDescription
--edgioVersionThe version of Edgio to install. Defaults to latest.
--skipEdgioDepsSkips installing Edgio packages.
--connectorThe name of a specific connector package to install, or a path to a directory that implements the connector interface.
--nameThe name of the property. Defaults to the name field in package.json.
--team, -tThe name of the organization under which the property belongs. Uses private space if omitted.
--originThe domain or IP address of the origin to use for the property.
--deployDeploys the property after initializing.
--skipFramework, --sfSkips installing the framework (Next.js, Vue, Angular, etc..) and simply rebundles your router.
--includeSourcesIncludes all non-gitignored source files in the bundle uploaded to Edgio. This can be helpful when debugging, especially when working with Edgio support. You can limit the files that are uploaded using the sources configuration in edgio.config.js.
--disablePermanentAssetsSet this to true to suppress errors like “Immutable file (…) content was changed” during deployment.
--propertyThe name of the property to deploy. By default the name field in edgio.config.js or package.json is used.
--skip-buildSkips running the edgio build command, including the framework build, and uses the previous build instead.
--pathPath to your site’s root directory. Uses current directory by default.
--branch, -bThe name of the source control branch. This is automatically set when using Git.
--environment, -eThe environment to deploy to. By default the default environment is used.
--commit-urlThe URL at which the commit can be viewed in your source control provided. If your package.json provides the repository attribute the commit URL will be derived automatically if you use GitHub, GitLab, or BitBucket.
--disable-team-checkSkips the check to see if the property is being deployed to a private space and also exists within an organization.

login

Logs in to Edgio through the Edgio Console.

Example

Bash
1edgio login

logout

Logs out of Edgio

Example

Bash
1edgio logout

ls

Lists all organizations, properties and environments associated with your account.

Example

Bash
1edgio ls

run

Runs your project locally, simulating Edgio cloud environment. When no arguments are provided, this command is the same as edgio dev.

Parameters

NameDescription
[archive] <path-to-zip-file>The path to a deployment archive (zip) file downloaded from Edgio Developer Console

Options

NameDescription
--production, -pRuns a production build of your app, simulating the cloud environment. This can also be achieved by setting the NODE_ENV environment variable to true. You need to run edgio build first.
--cache, -cEnables caching during local development so that you can test the caching logic in your router. By default caching is turned off in local development to ensure you don’t see stale responses as you make changes to your code.

Example

Bash
1edgio run --production
Or to run a deployment bundle downloaded from Edgio Console, use:
Bash
1edgio run /path/to/bundle.zip
Production mode is always used when running downloaded bundles.

use

Switches the version of all @edgio/* packages in your project.

Example

To install a particular version:
Bash
1edgio use 6.1.0
To install the latest stable version relative to your current version:
Bash
1edgio use latest
To install the latest preview:
Bash
1edgio use next

whoami

Outputs the email address associated with the logged in user.

Example

Bash
1edgio whoami

Troubleshooting


Error: Cannot find module … on edgio init

An uncommon issue when running edgio init can present a similar error:
installing @edgio/core, @edgio/cli, @edgio/prefetch, @edgio/devtools, @edgio/angular… done. Error: Cannot find module ‘/Users/myUser/Projects/my-@edgio-poc/node_modules/@edgio/angular/bin/init’
This may be related to an outdated global version of Edgio CLI. The telltale sign is reference to /bin/ in the module path. This is an old convention. Recommended approach would be to npm i -g @edgio/cli@latest and then run edgio init on the project.

Log Level Output

By default, Edgio CLI outputs logs at the INFO level. You may change this to obtain more output information of the CLI command being executed. To change the log level, set the LOG_LEVEL environment variable to one of the following values:
  • ERROR: Only errors are logged, providing critical information about issues and failures.
  • WARN: Errors and warnings are logged, offering insights into potential problems and anomalies.
  • INFO: Errors, warnings, and information are logged, presenting general operational information about the command being executed. (default)
  • DEBUG: Includes everything logged at the INFO level, plus additional debugging information, helpful for developers during development and testing.
  • TRACE: Includes all the information logged at the DEBUG level, and even more detailed information, useful for deep troubleshooting of code execution and performance analysis.
Example:
plaintext
1LOG_LEVEL=TRACE edgio run
2
3> Starting Edgio in development mode with caching disabled...
4> Building service worker... done.
5> Bundling router... done.
6> Bundling edge functions... done.
7> Recompile of router, config and edge functions... done.
8> Edgio ready on http://127.0.0.1:3000
9
10Next info - Loaded env from /Projects/edgio-docs/edgio-docs/.env
11Next warn - You have enabled experimental feature (scrollRestoration) in next.config.js.
12Next warn - Experimental features are not covered by semver, and may cause unexpected or broken application behavior. Use at your own risk.
13
14Next event - compiled client and server successfully in 14.9s (1498 modules)
15DEBUG [RequestHandler] GET /
16TRACE executed UriRaw: ModRewrite in 12ms
17TRACE executed UriClean: ModAccess in 12ms
18TRACE executed UriClean: ModRedirect in 6ms
19TRACE executed UriClean: ModSetEnv in 13ms
20TRACE executed UriClean: ModCache in 3ms
21TRACE executed UriClean: ModProxyFeatures in 4ms
22TRACE executed UriClean: ModStream in 1ms
23TRACE executed HandleDocRoot: ModCache in 0ms
24TRACE executed HandleDocRoot: ModTranscode in 0ms
25TRACE executed SendRequestContent: ModEdgeFunctions in 0ms
26TRACE Serverless hint proxy:0
27DEBUG [RequestContext] skipping to compute, function #0
28DEBUG [Backend] fetch {
29 protocol: 'http:',
30 slashes: true,
31 auth: null,
32 host: '127.0.0.1:3001',
33 port: '3001',
34 hostname: '127.0.0.1',
35 hash: null,
36 search: null,
37 query: [Object: null prototype] {},
38 pathname: '/',
39 path: '/',
40 href: 'http://127.0.0.1:3001/',
41 method: 'GET',
42 timeout: 0,
43 agent: null,
44 body: <Buffer >,
45 headers: {
46 host: '127.0.0.1:3001',
47 'user-agent': 'curl/8.1.2',
48 accept: '*/*',
49 'x-edg-serverless-hint': 'proxy:0',
50 'x-prerender-revalidate': '',
51 'x-forwarded-proto': 'http'
52 }
53}
54...