<br/>
<div align="center">
  <img src="https://cloudcache.tencent-cloud.com/qcloud/ui/static/static_source_business/8f2d5c70-8f06-4366-ae29-1a3eb9c7f602.svg" height="96">
  <h3 align="center">EdgeOne CLI</h3>
</div>

<br/>

## Overview

EdgeOne Makers is a front-end development and deployment platform built on Tencent EdgeOne infrastructure, designed for modern web development. It enables developers to quickly build and deploy static sites and serverless applications. By integrating edge function capabilities, it ensures efficient content delivery and dynamic functionality expansion, supporting fast access for users worldwide.

EdgeOne CLI can help you manage and debug Makers Functions in the project more efficiently.

<br/>

## 1. Preparations

- Quickly register and log in to the [Tencent Cloud Console](https://edgeone.ai/pages/new?s_url=https://console.tencentcloud.com/) using a Gmail account.

- Create a [Pages project](https://edgeone.ai/pages/new?s_url=https://console.tencentcloud.com/edgeone/pages) in the Console, and clone the repository to Local.

_If you are a China site user, please go to the corresponding [Pages](https://console.cloud.tencent.com/edgeone/pages) console._

<br />

## 2. Quick Start

### 1. Install

In the cloned project during the preparation stage, you can use npm to install the CLI:

```plaintext
npm install -g edgeone
```

Use the `edgeone -v` command to check if the installation is successful. Use the `edgeone -h` command to view all relevant commands.

###

### 2. Log in

Execute the login command, follow the prompts to select `Global` (International) or `China`, then complete the login in the pop-up browser window.

```plaintext
edgeone login
```

After completing the login, you can use the `edgeone whoami` command to view the current login account information.

### 3. Initialize

After successful login, execute the initialization command to initialize the basic environment required by EdgeOne Makers in the project:

```plaintext
edgeone makers init
```

After initialization, an `edge-functions` or `cloud-functions` folder and sample functions will be generated in the root directory of the project. You can continue to add and develop functions in this folder.

### 4. Local Development

After completing initialization, enter the local development stage:

```plaintext
edgeone makers dev
```

The run command by default creates a service locally on port 8088. Both the Makers Function service and the Makers project service run on the same port, with no need for additional proxying.

You can access the front-end page via `http://localhost:8088/`. In the front-end project, use the Fetch API directly, where the access path is the path of function files in folder `edge-functions` or `cloud-functions`.

```javascript
// ./cloud-functions/api/my-functions.js
fetch('/api/my-functions', {
  method: 'POST',
  body: JSON.stringify({ data: 'example' }),
});
```

Note:
- The dev service will read `devCommand` from `edgeone.json` to start your dev server. If absent, it will read the `dev` script from your project's `package.json`.
- Edge Functions debug service has a limit on the number of times it can start up, so try to avoid frequently logging out and starting the dev service (hot updates within the dev service will not increase the startup count).

### 5. Associated Project

If you need to use the Key-Value Storage capability or synchronize the environment variables set in the console to local debugging, you can execute the Associated Project commands, enter the project name as required. The project name here is the one created in the Preparation Work of the Makers project.

```plaintext
edgeone makers link
```
If you need to link a project that does not exist, you can also create a new project directly under the CLI guide.


### 6. Deploy

Build locally and deploy to EdgeOne Makers. If you need to link an existing project, it must be of the direct upload type.

```plaintext
edgeone makers deploy [<directoryOrZip>] [-n <projectName>] [-e <env>]
```

#### Parameters

- `<directoryOrZip>`: Path of folder or ZIP package to deploy
- `-n, --name`: Project name for deployment (creates new or updates existing project)
- `-e, --env`: Environment to deploy to, choices: 'production' or 'preview' (default: 'production')

Note:
- When you execute the deploy command, the CLI will automatically build and deploy your project.
- If you build manually, you need to place the Makers Functions related folders and `package.json` into the output directory (such as `dist`), and then run `edgeone makers deploy ./dist`.

#### Usage Examples

```plaintext
# Deploy build folder to production
edgeone makers deploy

# Deploy ZIP package to preview environment
edgeone makers deploy -e preview
```

**Alternative: Git-based Deployment**

You can also push the project code to the Git remote to trigger the CI build and deployment in the Makers backend, completing the entire development process.

### 7. Switching Accounts

If you need to switch to another Tencent Cloud account, you can execute the following command and then log in again:

```plaintext
edgeone switch
```

<br/>

## 3. CI/CD Integration

This section provides guidance on integrating EdgeOne CLI into your CI/CD pipelines for automated deployments.

### Automated Deploy Command

For CI/CD pipelines, you can use the same deploy command with an API Token for authentication:

```plaintext
edgeone makers deploy [<directoryOrZip>] -n <projectName> -t <token> [-e <env>]
```

#### Parameters

- `<directoryOrZip>`: Path of folder or ZIP package to deploy
- `-n, --name`: Project name for deployment (creates new or updates existing project) (required)
- `-e, --env`: Environment to deploy to, choices: 'production' or 'preview' (default: 'production')
- `-t, --token`: API Token for CI/CD pipelines (required for automated deployments)

Note:
- By default, when executing deploy, the CLI automatically builds and packages frontend code, `cloud-functions` (or `node-functions` for legacy projects), and `edge-functions` into the `.edgeone` folder and deploy to Makers.
- If you choose to build the project manually, you need to manually copy the Makers Functions related folder and `package.json` to dist (suppose the output directory is dist), then rerun `edgeone makers deploy ./dist`.

#### CI/CD Pipeline Examples

```plaintext
# Basic CI deployment to production with API token
edgeone makers deploy -n edgeone-pages-project -t $EDGEONE_API_TOKEN

# CI deployment to preview environment with API token
edgeone makers deploy -n edgeone-pages-project -e preview -t $EDGEONE_API_TOKEN
```

#### Obtaining an API Token

How to create an API Token

1. Access the Makers console and switch to the "API Token" Tab.
2. Click "Create API Token".
3. Enter "Token description" to help you remember the purpose of the API Token.
4. Select "expiration time" to ensure your information security.
5. Click Submit.

For more information, please refer to https://pages.edgeone.ai/document/api-token

<br/>

## 4. Environment Vars Management
```
// List all environment variables configured in the console
edgeone makers env ls


// Pull environment variables from the console to a local file
edgeone makers env pull
// Specify a local file when pulling environment variables
edgeone makers env pull -f .env.prod


// Add a new environment variable
edgeone makers env add ENV_VAR_KEY env_var_value


// Delete an environment variable
edgeone makers env rm ENV_VAR_KEY

```

## References

[Makers Introduction](https://pages.edgeone.ai/document/product-introduction) ｜ [Makers Functions](https://pages.edgeone.ai/document/pages-functions-overview)

_To access the China site documentation, please click [here](https://edgeone.cloud.tencent.com/pages/document/162936635171454976)._

<br/>

## Contact

If you need technical support, please [contact us](https://pages.edgeone.ai/contact?source=edgeone-cli).