Agents group commands, and CLI help/auth by liranfarage89 · Pull Request #135 · env0/env0-client-integrations

liranfarage89 · 2025-12-03T14:37:12Z

Summary

This PR extends the @env0/cli with a new agents command, modernizes how commands and arguments are wired, and refreshes the help output and README to better reflect current behavior.

Key themes:

New agents command group with agents list.
Centralized command metadata (handlers, required options, help) in one place.
Credentials continue to work via all existing methods (configure/env/flags), with -k/-s on runtime commands now deprecated rather than removed.
Cleaner, more conventional --help output.
Updated README with clearer usage and structure.

Changes

1. New `agents list` command (Agents Settings API)

Added agents list CLI command to list organization agents, backed by the /agents API endpoint.
- Usage:
```
env0 agents list -o <organizationId>
```

Implementation:

Handler: src/commands/agents-settings-list-agents.js
- Uses Env0ApiClient to call GET /agents with organizationId as a query param.
- Logs the JSON response using the existing logger.

Command config in src/config/commands.js:

'agents list': {
  handler: agentsSettingsListAgents,
  requiredOptions: ORG_REQUIRED_OPTIONS,   // apiKey, apiSecret, organizationId
  useDeployUtils: false,
  options: [argumentsMap[ORGANIZATION_ID]],
  help: [
    {
      desc: 'Lists organization agents',
      example: `$ env0 agents list -o <${ORGANIZATION_ID}>\n`
    }
  ]
}

organizationId is grouped under agents in src/config/arguments.js so it appears correctly in help output.

2. Centralized command wiring & required options

Before: run-command.js hard‑coded per‑command handlers and required options.
After: src/config/commands.js is the single source of truth:

Each command now has:
- handler – function implementing the command.
- requiredOptions – which options must be present.
- useDeployUtils – whether to initialize DeployUtils.
- options – CLI option schema for command-line-args.
- help – description and example(s) used for --help.
src/commands/run-command.js is now generic:
- Looks up commands[command] and uses the command’s requiredOptions / useDeployUtils / options instead of hard-coding.
- Initializes DeployUtils only when useDeployUtils is true.
- Calls commandConfig.handler(options, variables).

This makes adding new commands (including future agents <subcommand>s) primarily a matter of adding an entry in config/commands.js plus a handler module.

3. Auth flow: non-breaking, with deprecation warning

Goal: Improve auth UX by encouraging env0 configure and env vars, without breaking existing flows that rely on -k/-s.
Changes:
- In src/config/arguments.js:
  - apiKey / apiSecret (API_KEY, API_SECRET) remain defined with secret: true and are still available to runtime commands via shared base arguments.
  - organizationId is also grouped under agents so it is exposed for agents list.
- In src/config/commands.js:
  - Runtime commands (deploy, destroy, approve, cancel) once again use base argument sets that include apiKey / apiSecret, so -k/-s work as before.
  - agents list uses only organizationId as its explicit option, with credentials coming from configure/env/flags.
  - configure continues to expose -k/--apiKey and -s/--apiSecret for initial setup.
- In src/main.js:
  - New warnOnDeprecatedCredentialFlags helper detects use of -k/--apiKey and -s/--apiSecret (and their =value forms) on non-configure commands.
  - When present, a yellow deprecation warning is logged, but the flags are still passed through to commandLineArgs and configManager.read as before.
  - No argv mutation: behavior is non‑breaking; this is a warning-only change.
- In src/commands/help.js:
  - Help output hides any options whose schema has secret: true, so apiKey/apiSecret don’t show up under runtime commands, while remaining valid flags.
- config-manager behavior remains the same:
  - Merge order is still: config file < env vars < CLI params.
  - Existing tests (tests/lib/config-manager.spec.js) already assert:
    - Env vars override config file.
    - CLI params override env vars + config.
README updates:
- Clarifies that runtime commands can still accept apiKey / apiSecret flags for backwards compatibility, but these are now deprecated.
- Encourages using env0 configure and/or ENV0_API_KEY / ENV0_API_SECRET going forward.

4. Grouped `agents` commands and routing

src/main.js now supports grouped commands for agents:
- After handling internal commands (help/version/configure), any agents <subcommand> invocation is mapped:
```
if (command === "agents" && argv.length > 0) {
  command = `agents ${argv[0]}`;
  argv = argv.slice(1);
}
```
- This currently supports:
  - env0 agents list -o <organizationId>
- And will work for future subcommands like agents delete, agents update, etc., as long as they are defined in config/commands.js.
env0 agents --help is treated as an internal help call before remapping, so it shows a dedicated agents help page (see below) instead of trying to run a subcommand.

5. Help output improvements

File: src/commands/help.js
Top‑level help (env0 --help):
- Now a more conventional layout:
  - Usage – env0 <command> [options].
  - Commands – only top‑level commands (deploy, destroy, approve, cancel, configure, version, help, agents).
    - agents is summarized as:
      agents Manage agents (run `env0 agents --help` for subcommands)
  - Per-command ... options sections are rendered only for top-level commands (no spaces in name).
  - Examples – driven by each command’s help array from config/commands.js.
  - Footer with project URL.
Agents‑specific help (env0 agents --help):
- Uses a separate layout built from commands entries that start with agents :
  - Usage – env0 agents <command> [options].
  - Commands – currently:
```
agents list   Lists organization agents
```
  - agents list options – shows only organizationId.
  - Examples – only agents examples.
src/main.js passes the command into help(command) so:
- env0 --help → top-level help.
- env0 agents --help → agents‑specific help.

6. Tests

Existing tests for run-command, deploy, destroy, config-manager, etc., continue to validate behavior around required options and config/env precedence.
Given this PR is focused on behavior and compatibility rather than new core flows, the primary safeguards are the existing suite plus manual verification of:
- env0 --help top-level layout.
- env0 agents --help grouped agents help.
- env0 agents list -o <org> with credentials coming from configure / env vars / -k/-s.

7. README refresh

File: node/README.md
Modernized and aligned with current behavior:
- Documents:
  - Installation and usage.
  - Quick start (configure → deploy → --help / agents --help).
  - Configuration & authentication, including precedence and the fact that runtime commands can still accept apiKey / apiSecret flags for backwards compatibility, but these flags are now deprecated and env0 configure / env vars are preferred.
  - Commands: deploy, destroy, approve, cancel, grouped agents commands (currently agents list), configure, version, help.
  - Arguments and environment variables.
  - Project structure (where to look to add new commands, especially grouped ones).
  - Development flow (install, test, lint, custom ENV0_API_URL).

Notes for reviewers

Backward compatibility:
- All existing auth flows remain supported:
  - env0 configure.
  - ENV0_API_KEY / ENV0_API_SECRET env vars.
  - -k/-s flags on runtime commands, now accompanied by a deprecation warning instead of a behavior change.
- Top‑level --help is more concise; detailed per‑subcommand help is available via env0 agents --help.
Extensibility:
- New commands (especially under agents) can be added by:
  1. Adding an entry in src/config/commands.js (with handler, requiredOptions, useDeployUtils, options, help).
  2. Implementing the handler in src/commands/….
- No changes are required in main.js or run-command.js for additional agents <subcommand> entries.

…mand config

chpl

node 18 is not supported anymore
changing auth method is breaking change - you should keep any existing configuration method
split into multiple PRs

…lient-integrations into feat/cli-agents-settings-list-agents

liranfarage89 · 2025-12-08T13:51:17Z

node 18 is not supported anymore

changing auth method is breaking change - you should keep any existing configuration method

split into multiple PRs

@chpl

Thanks for the review and the notes.

Node version
- Updated the CLI to require Node >= 20.
- CI and publish workflows now use Node 20.x.
- README now states “Requires Node 20+”.
Auth behavior (no breaking change)
- All existing auth methods remain supported:
  - env0 configure.
  - ENV0_API_KEY / ENV0_API_SECRET.
  - -k/--apiKey and -s/--apiSecret on runtime commands.
- I added a yellow deprecation warning when -k/-s are used on non-configure commands, but I don’t strip or reject them, so existing scripts keep working.
- Help output hides secret options so apiKey/apiSecret don’t show up under runtime commands, and the README encourages using configure/env going forward.
PR size / future PRs
- I’ve split out a separate Node 20 upgrade branch/PR so the version bump is isolated.
- This PR now focuses on CLI behavior: auth deprecation warning, agents group/agents list, and help/README improvements.

… tests

chpl · 2025-12-09T11:33:14Z

node/src/main.js

+const DEPRECATED_CREDENTIAL_FLAGS = ['-k', '--apiKey', '-s', '--apiSecret'];
+
+const warnOnDeprecatedCredentialFlags = (command, argv) => {
+  if (command === 'configure') return;
+
+  const hasDeprecatedFlag = argv.some(arg => {
+    if (DEPRECATED_CREDENTIAL_FLAGS.includes(arg)) return true;
+    return (
+      arg.startsWith('--apiKey=') ||
+      arg.startsWith('-k=') ||
+      arg.startsWith('--apiSecret=') ||
+      arg.startsWith('-s=')
+    );
+  });
+
+  if (hasDeprecatedFlag) {
+    const YELLOW = '\u001b[33m';
+    const RESET = '\u001b[0m';
+    logger.info(
+      `${YELLOW}Warning: -k/--apiKey and -s/--apiSecret are deprecated for this command and may be removed in a future version. Prefer using "env0 configure" or ENV0_API_KEY/ENV0_API_SECRET instead.${RESET}`
+    );
+  }
+};
+


why deprecate it?

it's bad practice to pass sensitive variables like that, isn't it?

Remove command prefix grouping logic from getCommandOptions and return parsed options directly. Export getCommandOptions for testing. Update test mocks to match new flat structure without command key nesting.

…g file Update config merge order in config-manager to prioritize environment variables over CLI parameters. Add tests to verify env vars take precedence in both scenarios with and without config file. Add test coverage for agents-settings-list-agents command.

liranfarage89 · 2025-12-09T15:31:48Z

closing this for now

feat(cli): add agents-settings-list-agents command and centralize com…

8373120

…mand config

github-actions bot assigned liranfarage89 Dec 3, 2025

liranfarage89 added 5 commits December 3, 2025 17:13

upgrade node version

abc9818

removed apiKey and secret flags from deploy commands

0ea6dff

agents list command

0191d29

feat(cli): refine agents group commands and help output

ba5e064

updated readme

aa98098

liranfarage89 changed the title ~~Add agents-settings-list-agents CLI command~~ Update Node Version to 18.x + agents command + refactoring Dec 3, 2025

liranfarage89 requested a review from a team December 3, 2025 16:18

liranfarage89 added the pending final review label Dec 3, 2025

chpl reviewed Dec 3, 2025

View reviewed changes

chore(cli): apply review comments (node 20, auth deprecation, help)

affb61d

liranfarage89 changed the base branch from master to feat/node-20-upgrade December 8, 2025 13:37

liranfarage89 changed the base branch from feat/node-20-upgrade to master December 8, 2025 13:46

liranfarage89 changed the base branch from master to feat/node-20-upgrade December 8, 2025 13:47

Merge branch 'feat/node-20-upgrade' of https://github.com/env0/env0-c…

d760028

…lient-integrations into feat/cli-agents-settings-list-agents

test(cli): filter secret options from visibility checks in auth flags…

c17fbe6

… tests

liranfarage89 changed the title ~~Update Node Version to 18.x + agents command + refactoring~~ Update Node 20, agents group commands, and CLI help/auth Dec 8, 2025

fix lint

381559b

liranfarage89 changed the title ~~Update Node 20, agents group commands, and CLI help/auth~~ Agents group commands, and CLI help/auth Dec 8, 2025

liranfarage89 requested a review from chpl December 8, 2025 15:59

chpl reviewed Dec 9, 2025

View reviewed changes

chpl approved these changes Dec 9, 2025

View reviewed changes

liranfarage89 added 6 commits December 9, 2025 15:22

dev version

edfaab3

fix(cli): fallback to all command options when prefix not found

363d00a

dev version

ac266c4

refactor(cli): simplify command options parsing and update tests

6a3adfe

Remove command prefix grouping logic from getCommandOptions and return parsed options directly. Export getCommandOptions for testing. Update test mocks to match new flat structure without command key nesting.

fix(cli): update main module import to use destructured run function

b08fa7a

dev version

bd31db4

liranfarage89 closed this Dec 9, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Agents group commands, and CLI help/auth#135

Agents group commands, and CLI help/auth#135
liranfarage89 wants to merge 17 commits intofeat/node-20-upgradefrom
feat/cli-agents-settings-list-agents

liranfarage89 commented Dec 3, 2025 •

edited

Loading

Uh oh!

chpl left a comment •

edited

Loading

Uh oh!

liranfarage89 commented Dec 8, 2025

Uh oh!

chpl Dec 9, 2025

Uh oh!

liranfarage89 Dec 9, 2025

Uh oh!

liranfarage89 commented Dec 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

liranfarage89 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

1. New agents list command (Agents Settings API)

2. Centralized command wiring & required options

3. Auth flow: non-breaking, with deprecation warning

4. Grouped agents commands and routing

5. Help output improvements

6. Tests

7. README refresh

Notes for reviewers

Uh oh!

chpl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liranfarage89 commented Dec 8, 2025

Uh oh!

chpl Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

liranfarage89 Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

liranfarage89 commented Dec 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

liranfarage89 commented Dec 3, 2025 •

edited

Loading

1. New `agents list` command (Agents Settings API)

4. Grouped `agents` commands and routing

chpl left a comment •

edited

Loading