feat(command-env): add support for plaintext output in env:list

[tinfoil-knight]

🎉 Thanks for submitting a pull request! 🎉

Summary

Fixes #3262

The env:list command currently outputs an ASCII table by default which isn't helpful if someone intends to write the environment variables to a file.

The --plain flag introduced in this PR would allow a user to setup their env files easily on local systems since it outputs the environment variables in the plaintext format used in .env files.

Example Output here:

$ netlify env:list --plain
NODE_ENV=development
REACT_APP_API_URL=https://api.netlify.com
REACT_APP_SECRET=UILH0lQphn

Also see: #3262 (comment)

---

For us to review and ship your PR efficiently, please perform the following steps:

• Open a bug/issue before writing your code 🧑‍💻. This ensures we can discuss the changes and get feedback from everyone that should be involved. If you`re fixing a typo or something that`s on fire 🔥 (e.g. incident related), you can skip this step.
• Read the contribution guidelines 📖. This ensures your code follows our style guide and
  passes our tests.
• Update or add tests (if any source code was changed or added) 🧪
• Update or add documentation (if features were changed or added) 📝
• Make sure the status checks below are successful ✅

A picture of a cute animal (not mandatory, but encouraged)
🦥

[github-actions]

📊 Benchmark results

Comparing with 0bc18bb

Package size: 249 MB

(no change)

^  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB  249 MB 
│   ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐    ┌──┐  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
│   |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |  |    |▒▒|  
└───┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴────┴──┴──>
    T-12    T-11    T-10    T-9     T-8     T-7     T-6     T-5     T-4     T-3     T-2     T-1      T    

Legend

• T-30 (fd7db45): 247 MB
• T-29 (57ee933): 247 MB
• T-28 (26c409d): 247 MB
• T-27 (38f548f): 247 MB
• T-26 (ff1eecb): 254 MB
• T-25 (990da12): 254 MB
• T-24 (869c5a8): 254 MB
• T-23 (62930d8): 254 MB
• T-22 (345ce9c): 254 MB
• T-21 (0041559): 254 MB
• T-20 (e65f97c): 254 MB
• T-19 (35123df): 254 MB
• T-18 (a49e5fc): 249 MB
• T-17 (6214768): 242 MB
• T-16 (acdcbb6): 242 MB
• T-15 (743b4d6): 242 MB
• T-14 (f9f45ed): 249 MB
• T-13 (22de9e2): 249 MB
• T-12 (d64c875): 249 MB
• T-11 (cd993b0): 249 MB
• T-10 (9a7c666): 249 MB
• T-9 (cf2f402): 249 MB
• T-8 (6102e77): 249 MB
• T-7 (d3dfa17): 249 MB
• T-6 (9bb51a1): 249 MB
• T-5 (81ac0c6): 249 MB
• T-4 (bb16cec): 249 MB
• T-3 (3ff4a57): 249 MB
• T-2 (3b491be): 249 MB
• T-1 (0bc18bb): 249 MB
• T (current commit): 249 MB

[jasonbarry]

Amazing, thanks so much for pushing this along @tinfoil-knight!! 🙌

I have a request that shouldn't be too much lift: considering that we also have the undocumented --json flag, and that --json --plain doesn't make much sense, could this change to --format <format>?

• --format would have an array of choices of table, plain, and json, with table being the default
• options.json should still be supported on line 71, alongside options.format === 'json', to preserve backwards-compatibility

Let me know what you think. Thanks again for making this contribution! 💯

[jasonbarry]

Could new entries to the help be put below scope? Would be nice to keep context and scope next to each other. Thanks!

[tinfoil-knight]

The plain flag in between seemed weird to me too but the options are sorted here to produced the documentation:

cli/src/utils/command-helpers.mjs

Lines 74 to 80 in d3dfa17

	export const sortOptions = (optionA, optionB) => {
	// base flags should be always at the bottom
	if (BASE_FLAGS.has(optionA.long) || BASE_FLAGS.has(optionB.long)) {
	return -1
	}
	return optionA.long.localeCompare(optionB.long)
	}

Although, we can rename the option to text so it appear after scope.

---

Other alternatives like raw, plaintext would appear in between context & scope in the sorted order.

Let me know if you've a better suggestion or if we should go ahead with text.

[jasonbarry]

Gotcha -- let's keep it as plain, and let the docs sort them as they currently do. But in --help, it would be great if context and scope could appear next to each other.

[tinfoil-knight]

Unfortunately, it seems like we're using the same function to order the help output too so I don't think the re-ordering would be possible unless we rename the option.

The current order does appear a bit weird to me too but I don't think there's any way to override this specific instance.

Ref:

cli/src/commands/base-command.mjs

Lines 249 to 256 in 3ff4a57

	const optionList = helper
	.visibleOptions(command)
	.sort(sortOptions)
	.map((option) => formatItem(helper.optionTerm(option), helper.optionDescription(option)))
	if (optionList.length !== 0) {
	output = [...output, chalk.bold('OPTIONS'), formatHelpList(optionList), '']
	}
	}

[tinfoil-knight]

I have a request that shouldn't be too much lift: considering that we also have the undocumented --json flag, and that --json --plain doesn't make much sense, could this change to --format <format>?

• --format would have an array of choices of table, plain, and json, with table being the default
• options.json should still be supported on line 71, alongside options.format === 'json', to preserve backwards-compatibility

@jasonbarry I'm slightly opposed to making the suggested changes.

• The default flow first prints the table with env values hidden (key, scope visible) & then asks if the user wants to print the actual env values or not. The --json & --plain flags just print the env key & values directly which makes their behaviour different than the default one. I don't think values passed to the --format flag should have different behaviour (apart from the output format).

• The --json flag is used across a lot of commands across the CLI so users familiar with the CLI would expect the JSON output for relevant commands to be accessible through the same flag. Adding the new --format flag to env:list would make this experience inconsistent with rest of the CLI commands.

WDYT?

P.S. I found a way to avoid the conflict with --json --plain.

The commander CLI framework supports adding a conflicts property to the options to prevent conflicting options from being used together.

$ ncli env:list --json --plain
 ›   Error: option '--plain' cannot be used with option '--json'
 ›   See more help with --help

[jasonbarry]

Sounds like a plan @tinfoil-knight, thanks for the research and explanation. I'd be happy to approve with this proposal if a conflicts property is added.

[tinfoil-knight]

@jasonbarry The conflicts property has been added now to prevent the --json & --plain flags from being used together.

[jasonbarry]

Awesome work @tinfoil-knight, thanks for adding this feature!