From 7ced04f9e736b10afb7673b2918285850e43fb63 Mon Sep 17 00:00:00 2001 From: Liran Farage <83922349+liranfarage89@users.noreply.github.com> Date: Mon, 8 Dec 2025 15:35:27 +0200 Subject: [PATCH] chore(cli): require Node 20 and update CI/publish workflows --- .github/workflows/ci.yml | 4 +- .github/workflows/publish-npm.yml | 2 +- node/README.md | 348 ++++++++++++++++++++---------- node/npm-shrinkwrap.json | 2 +- node/package.json | 2 +- 5 files changed, 244 insertions(+), 114 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 51f7df7..cd6a688 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,10 +13,10 @@ jobs: steps: - uses: actions/checkout@v1 - - name: Use Node.js 14.x + - name: Use Node.js 20.x uses: actions/setup-node@v1 with: - node-version: 14.x + node-version: 20.x - name: install dependencies working-directory: ${{ matrix.package }} run: yarn diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 714eaa3..dbf060e 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -15,7 +15,7 @@ jobs: # Setup .npmrc file to publish to npm - uses: actions/setup-node@v2 with: - node-version: '16.x' + node-version: '20.x' registry-url: 'https://registry.npmjs.org' - run: npm ci - run: npm publish --access public diff --git a/node/README.md b/node/README.md index ede339c..3a46804 100644 --- a/node/README.md +++ b/node/README.md @@ -1,141 +1,227 @@ +# @env0/cli [![License](https://img.shields.io/npm/l/@env0/cli?color=blue)](https://github.com/env0/env0-client-integrations/blob/master/LICENSE) [![Version](https://img.shields.io/npm/v/@env0/cli)](https://www.npmjs.com/package/@env0/cli) [![Downloads](https://img.shields.io/npm/dw/@env0/cli)](https://www.npmjs.com/package/@env0/cli) [![CI](https://github.com/env0/env0-client-integrations/workflows/CI/badge.svg?branch=master)](https://github.com/env0/env0-client-integrations/actions?query=workflow%3ACI+branch%3Amaster) -# @env0/cli [![License](https://img.shields.io/npm/l/@env0/cli?color=blue)](https://github.com/env0/env0-client-integrations/blob/master/LICENSE) [![Version](https://img.shields.io/npm/v/@env0/cli)](https://www.npmjs.com/package/@env0/cli) [![Downloads](https://img.shields.io/npm/dw/@env0/cli)](https://www.npmjs.com/package/@env0/cli) [![CI](https://github.com/env0/env0-client-integrations/workflows/CI/badge.svg?branch=master)](https://github.com/env0/env0-client-integrations/actions?query=workflow%3ACI+branch%3Amaster) - -The command-line tool for the env0 platform. +The official command-line tool for the [env0](https://www.env0.com) platform. -- [Commands](#commands-overview) -- [Arguments](#arguments-overview) +It lets you deploy, destroy, and manage environments as code from your terminal, and also exposes grouped commands for managing agents. -## Features +--- - - **deploy** - Creates a new environment or deploy an existing environment. - - **destroy** - Destroys an existing environment. - - **approve** - Resumes a deployment that awaits an approval. - - **cancel** - Cancels a deployment that awaits an approval. +- [Installation](#installation) +- [Quick start](#quick-start) +- [Configuration & authentication](#configuration--authentication) +- [Commands](#commands) + - [deploy](#env0-deploy) + - [destroy](#env0-destroy) + - [approve](#env0-approve) + - [cancel](#env0-cancel) + - [agents](#env0-agents-grouped-commands) + - [configure](#env0-configure) +- [Arguments](#arguments) +- [Environment variables](#environment-variables) +- [Project structure](#project-structure) +- [Development](#development) + +--- ## Installation ```bash -$ yarn global add @env0/cli +yarn global add @env0/cli # or -$ npm install -g @env0/cli +npm install -g @env0/cli ``` -## Commands Overview +Requires **Node 20+**. + +--- + +## Quick start + +1. **Configure credentials and defaults** (one time): + + ```bash + env0 configure + ``` + + This will interactively prompt for: + + - API key / secret + - Organization ID + - Default project / environment / blueprint + + Values are saved to `~/.env0/config.json` and automatically reused. + +2. **Run a deployment**: + + ```bash + env0 deploy -o -p -b -e + ``` + +3. **Get help at any time**: + + ```bash + env0 --help + env0 agents --help + ``` + +--- + +## Configuration & authentication + +The CLI reads configuration from three places, in this order of precedence (highest first): + +1. **Explicit CLI flags** (e.g. `-o`, `-p`) +2. **Environment variables** (e.g. `ENV0_API_KEY`) +3. **Configuration file** at `~/.env0/config.json` -### `env0 help` +Authentication is normally provided via **configure** or environment variables: -Run `env0 help` to get a helpful list of supported commands and arguments. +- Run `env0 configure` to set: -### `env0 configure ` + - `apiKey`, `apiSecret` + - `organizationId`, `projectId`, `environmentName`, `blueprintId` -Sets configurable options for the CLI. -If no arguments are given, displays a set of prompts that will help you configure the CLI options. +- Or set env vars (see [Environment variables](#environment-variables)). -### `env0 deploy ` +Runtime commands (like `deploy`, `destroy`, `approve`, `cancel`, `agents list`) can still accept `apiKey` / `apiSecret` flags for backwards compatibility, but these flags are **deprecated**. Prefer using `env0 configure` or `ENV0_API_KEY` / `ENV0_API_SECRET`. -Initiates a new deployment on env0, whether for a new environment or for an existing one. +--- -### `env0 destroy ` +## Commands -Initiates a new deployment to destroy and existing environment. +You can always see the latest list and options via: -### `env0 approve ` +```bash +env0 --help +``` + +### `env0 deploy` + +Deploys an environment. + +Examples: + +```bash +env0 deploy -o -p -b -e +env0 deploy -o -p -b -e -r main -v stage=dev -u tfvar=value +``` -Runs an approval of an existing deployment that is waiting to be approved (AKA waiting in plan stage). +Key options: -### `env0 cancel ` +- `-o, --organizationId` – env0 Organization ID (required) +- `-p, --projectId` – env0 Project ID (required) +- `-b, --blueprintId` – Blueprint to deploy (required for new environments) +- `-e, --environmentName` – Environment name +- `--environmentId` – Environment ID (takes precedence over name) +- `-r, --revision` – Git revision (branch/tag/commit) +- `-v, --environmentVariables` – Environment variables (`NAME=value`) +- `-q, --sensitiveEnvironmentVariables` – Sensitive environment variables +- `-u, --terraformVariables` – Terraform variables (`NAME=value`) +- `-a, --requiresApproval` – `true`/`false` +- `-z, --skipStateRefresh` – Skip state refresh on destroy plan +- `-t, --targets` – Partial apply targets list -Cancels an existing deployment that is waiting to be approved (AKA waiting in plan stage). +### `env0 destroy` -## Arguments Overview +Destroys an environment. -The arguments are loaded from env0 configuration files, environment variables and CLI parameters. -The order of precedence of the arguments is: -1. `env0` CLI explicit parameters -2. Environment Variables -3. Configuration File +```bash +env0 destroy -o -p -e +``` -### API Key -> env0 API Key (Required) -- Usage: `--apiKey` -- Alias: `-k` +Uses `requiresApproval` / `skipStateRefresh` to control behavior. -### API Secret -> env0 API Secret (Required) -- Usage: `--apiSecret` -- Alias: `-s` +### `env0 approve` -### Organization ID -> env0 Organization ID (Required) -- Usage: `--organizationId` -- Alias: `-o` +Approves a deployment that is waiting for user approval. -### Project ID -> env0 Project ID (Required) -- Usage: `--projectId` -- Alias: `-p` +```bash +env0 approve -o -p -e +``` -### Blueprint ID -> The Blueprint ID you wish to deploy with (Required for new environments) -- Usage: `--blueprintId` -- Alias: `-b` +### `env0 cancel` -### Environment Name -> The environment name you wish to create, or deploy to an existing one (Required for existing environments) -- Usage: `--environmentName` -- Alias: `-e` +Cancels a deployment that is waiting for user approval. -### Environment ID -> The environment id you wish to re-deploy. If both the environment name and ID are specified, the environment ID will take precedence -- Usage: `--environmentId` -- Alias: N/A +```bash +env0 cancel -o -p -e +``` -### Workspace Name -> (Optional) - A name for Terraform Workspace created for your new environment. This cannot be changed after an environment was created -- Usage: `--workspaceName` -- Alias: `-w` +### `env0 agents` (grouped commands) -### Environment Variables -> The environment variables to set on the deployed environment - works only on deploy and can be multiple, the format is "environmentVariableName1=value" -- Usage: `--environmentVariables` -- Alias: `-v` +`agents` is a **group** command. Use: -For sensitive environment variables, use: -- Usage: `--sensitiveEnvironmentVariables` -- Alias: `-q` +```bash +env0 agents --help +``` -### Terraform Variables -> The terraform variables to set on the deployed environment - works only on deploy and can be multiple, the format is "terraformVariableName1=value" -- Usage: `--terraformVariables` -- Alias: `-u` +to see all agents-related subcommands. Currently supported: -### Revision -> Your GIT revision, can be a branch, a tag or a commit hash. (For existing environments - if not specified, will use the previously defined revision) -- Usage: `--revision` -- Alias: `-r` +- **`env0 agents list`** – List agents for an organization. -### Requires Approval -> Requires approval for deployment. Valid values are either "true" or "false". -- Usage: `--requiresApproval ` -- Alias: `-a` + ```bash + env0 agents list -o + ``` -### Skip State Refresh -> Disable automatic state refresh on 'plan -destroy' phase. -- Usage: `--skipStateRefresh ` -- Alias: `-z` +Future commands (e.g. `agents delete`, `agents update`) will follow the same pattern. -### Targets (Partial Apply) -> A list of resources to explicitly include in the deployment, delimited by a comma. Format is "resource1,resource2,resource3" -- Usage: `--targets` -- Alias: `-t` +### `env0 configure` -## Configuration File -After initial deployment, a configuration file will be created under `~/.env0/config.json` +Configures env0 CLI options. -This file holds your last action's required parameters and will spare you from re-configuring the required parameters on every action. +- **Interactive** (no flags): -## Supported Environment Variables + ```bash + env0 configure + ``` + +- **Non-interactive** (flags): + + ```bash + env0 configure -k -s -o -p -e -b + ``` + +Options you pass here are merged with existing config and written to `~/.env0/config.json`. + +### `env0 version` / `env0 help` + +- `env0 --version` or `env0 version` – print CLI version. +- `env0 --help` or `env0 help` – show global help. + +--- + +## Arguments + +Most arguments are shared across commands. Below is a quick reference (see `env0 --help` for the canonical list). + +- **API Key / Secret** (used via config/env) + + - `apiKey` – env0 API Key + - `apiSecret` – env0 API Secret + +- **Core identifiers** + + - `organizationId` (`-o`) – env0 Organization ID + - `projectId` (`-p`) – env0 Project ID + - `environmentName` (`-e`) – environment name + - `environmentId` – environment ID + - `blueprintId` (`-b`) – blueprint ID + +- **Deployment configuration** + - `workspaceName` (`-w`) + - `environmentVariables` (`-v`) + - `sensitiveEnvironmentVariables` (`-q`) + - `terraformVariables` (`-u`) + - `revision` (`-r`) + - `requiresApproval` (`-a`) + - `skipStateRefresh` (`-z`) + - `targets` (`-t`) + +--- + +## Environment variables + +Supported env vars: - `ENV0_API_KEY` - `ENV0_API_SECRET` @@ -145,26 +231,70 @@ This file holds your last action's required parameters and will spare you from r - `ENV0_ENVIRONMENT_NAME` - `ENV0_ENVIRONMENT_ID` -## API Reference +These are read by the config manager and merged with the config file and CLI flags. -https://docs.env0.com/reference +You can also override the API endpoint for development: -## env0 blog: +```bash +export ENV0_API_URL=https://api-server +# default is https://api.env0.com +``` + +--- + +## Project structure -https://www.env0.com/blog/introducing-the-env0-cli +Relevant files for the CLI behavior: +- `bin/cli.js` – Node entrypoint (`env0` binary) that loads `src/main.js`. +- `src/main.js` – Top-level CLI flow: parses the main command, handles internal commands + (`help`, `version`, `configure`), routes grouped commands (e.g. `agents `), + and invokes `run-command`. +- `src/commands/run-command.js` – Shared orchestration for runtime commands: + reads config, validates required options, initializes deploy utils when needed, and + calls the specific command handler. +- `src/config/commands.js` – Central command registry: + - `handler` – function implementing the command + - `requiredOptions` – which options must be present + - `useDeployUtils` – whether to initialize deploy utilities + - `options` – CLI option schema passed to `command-line-args` + - `help` – descriptions and examples used in `--help` +- `src/config/arguments.js` – Shared argument definitions (names, aliases, descriptions, groups). +- `src/commands/*` – Individual command handlers (`deploy`, `destroy`, `approve`, `cancel`, `configure`, agents commands, etc.). +- `src/commands/help.js` – Renders help output using `command-line-usage`, including the grouped + `agents` help when invoked as `env0 agents --help`. -## Compiling from Source +This structure is designed so adding new commands (including new `agents `s) is primarily +a matter of wiring them into `config/commands.js` and providing a handler. + +--- + +## Development + +Clone the repo and work from the `node` directory: -You can compile and run the CLI from source by cloning the repo from Github and then running the following: ```bash -# Clone the repo from github -# Make sure env0 lib is not installed globally -npm install -npm link # link your local copy of the CLI to your terminal path +git clone https://github.com/env0/env0-client-integrations.git +cd env0-client-integrations/node + +# install deps (npm, yarn, or pnpm) +pnpm install + +# run tests +pnpm test + +# run lint +pnpm lint ``` -### Development flow: -- Run `export ENV0_API_URL=https://api-server` to change the API URL -Default url is set to `https://api.env0.com` -- Run `env0 configure` +During development you can point the CLI at a custom env0 API URL: + +```bash +export ENV0_API_URL=https://api-server +env0 configure +``` + +## API Reference & blog + +- API Reference: https://docs.env0.com/reference +- Blog: https://www.env0.com/blog/introducing-the-env0-cli diff --git a/node/npm-shrinkwrap.json b/node/npm-shrinkwrap.json index 1f632ab..77c64a2 100644 --- a/node/npm-shrinkwrap.json +++ b/node/npm-shrinkwrap.json @@ -32,7 +32,7 @@ "prettier": "2.0.5" }, "engines": { - "node": ">=14" + "node": ">=20" } }, "node_modules/@ampproject/remapping": { diff --git a/node/package.json b/node/package.json index dbfb871..e578344 100644 --- a/node/package.json +++ b/node/package.json @@ -8,7 +8,7 @@ "directory": "node" }, "engines": { - "node": ">=14" + "node": ">=20" }, "bugs": { "url": "https://github.com/env0/env0-client-integrations/issues"