Merge pull request #1124 from balena-io/conditional-debug-hint

Minor doc updates (add DEBUG=1 hint)

doc/cli.markdown

@@ -589,17 +589,14 @@ path to the config JSON file, see `balena os build-config`
 
 ## envs
 
-Use this command to list all environment variables for
+Use this command to list the environment variables of an application
-a particular application or device.
+or device.
 
-This command lists all application/device environment variables.
+The --config option is used to list "config" variables that configure
+balena features.
 
-If you want to see config variables, used to configure
+Service-specific variables are not currently supported. The following
-balena features, use the --config option.
+examples list variables that apply to all services in an app or device.
-
-At the moment the CLI does not support per-service variables,
-so the following commands will only show service-wide
-environment variables.
 
 Example:
 
@@ -623,12 +620,16 @@ show config variables
 
 ## env rm <id>
 
-Use this command to remove an environment variable from an application.
+Use this command to remove an environment variable from an application
+or device.
 
 Notice this command asks for confirmation interactively.
 You can avoid this by passing the `--yes` boolean option.
 
-If you want to eliminate a device environment variable, pass the `--device` boolean option.
+The --device option selects a device instead of an application.
+
+Service-specific variables are not currently supported. The following
+examples remove variables that apply to all services in an app or device.
 
 Examples:
 
@@ -648,10 +649,8 @@ device
 
 ## env add <key> [value]
 
-Use this command to add an enviroment or config variable to an application.
+Use this command to add an enviroment or config variable to an application
-
+or device.
-At the moment the CLI doesn't fully support multi-container applications,
-so the following commands will set service-wide environment variables.
 
 If value is omitted, the tool will attempt to use the variable's value
 as defined in your host machine.
@@ -662,6 +661,9 @@ to a specific device.
 If the value is grabbed from the environment, a warning message will be printed.
 Use `--quiet` to remove it.
 
+Service-specific variables are not currently supported. The following
+examples set variables that apply to all services in an app or device.
+
 Examples:
 
 	$ balena env add EDITOR vim --application MyApp
@@ -680,9 +682,13 @@ device uuid
 
 ## env rename <id> <value>
 
-Use this command to change the value of an enviroment variable.
+Use this command to change the value of an application or device
+enviroment variable.
 
-Pass the `--device` boolean option if you want to rename a device environment variable.
+The --device option selects a device instead of an application.
+
+Service-specific variables are not currently supported. The following
+examples modify variables that apply to all services in an app or device.
 
 Examples:
 

lib/actions/environment-variables.ts

@@ -44,17 +44,14 @@ export const list: CommandDefinition<
 	signature: 'envs',
 	description: 'list all environment variables',
 	help: stripIndent`
-		Use this command to list all environment variables for
+		Use this command to list the environment variables of an application
-		a particular application or device.
+		or device.
 
-		This command lists all application/device environment variables.
+		The --config option is used to list "config" variables that configure
+		balena features.
 
-		If you want to see config variables, used to configure
+		Service-specific variables are not currently supported. The following
-		balena features, use the --config option.
+		examples list variables that apply to all services in an app or device.
-
-		At the moment the CLI does not support per-service variables,
-		so the following commands will only show service-wide
-		environment variables.
 
 		Example:
 
@@ -129,12 +126,16 @@ export const remove: CommandDefinition<
 	signature: 'env rm <id>',
 	description: 'remove an environment variable',
 	help: stripIndent`
-		Use this command to remove an environment variable from an application.
+		Use this command to remove an environment variable from an application
+		or device.
 
 		Notice this command asks for confirmation interactively.
 		You can avoid this by passing the \`--yes\` boolean option.
 
-		If you want to eliminate a device environment variable, pass the \`--device\` boolean option.
+		The --device option selects a device instead of an application.
+
+		Service-specific variables are not currently supported. The following
+		examples remove variables that apply to all services in an app or device.
 
 		Examples:
 
@@ -183,10 +184,8 @@ export const add: CommandDefinition<
 	signature: 'env add <key> [value]',
 	description: 'add an environment or config variable',
 	help: stripIndent`
-		Use this command to add an enviroment or config variable to an application.
+		Use this command to add an enviroment or config variable to an application
-
+		or device.
-		At the moment the CLI doesn't fully support multi-container applications,
-		so the following commands will set service-wide environment variables.
 
 		If value is omitted, the tool will attempt to use the variable's value
 		as defined in your host machine.
@@ -197,6 +196,9 @@ export const add: CommandDefinition<
 		If the value is grabbed from the environment, a warning message will be printed.
 		Use \`--quiet\` to remove it.
 
+		Service-specific variables are not currently supported. The following
+		examples set variables that apply to all services in an app or device.
+
 		Examples:
 
 			$ balena env add EDITOR vim --application MyApp
@@ -262,9 +264,13 @@ export const rename: CommandDefinition<
 	signature: 'env rename <id> <value>',
 	description: 'rename an environment variable',
 	help: stripIndent`
-		Use this command to change the value of an enviroment variable.
+		Use this command to change the value of an application or device
+		enviroment variable.
 
-		Pass the \`--device\` boolean option if you want to rename a device environment variable.
+		The --device option selects a device instead of an application.
+
+		Service-specific variables are not currently supported. The following
+		examples modify variables that apply to all services in an app or device.
 
 		Examples:
 

lib/utils/messages.ts

@@ -1,15 +1,22 @@
+const DEBUG_MODE = !!process.env.DEBUG;
+
 export const reachingOut = `\
 If you need help, or just want to say hi, don't hesitate in reaching out at:
 
-  GitHub: https://github.com/balena-io/balena-cli/issues/new
+  Forums: https://forums.balena.io
-  Forums: https://forums.balena.io\
+  GitHub: https://github.com/balena-io/balena-cli/issues/new\
 `;
 
-export const getHelp = `\
+const debugHint = `\
+Additional information may be available in debug mode. Prefix the command
+line with DEBUG=1, i.e.:  DEBUG=1 balena ...
+`;
+
+export const getHelp = `${DEBUG_MODE ? '' : debugHint}\
 If you need help, don't hesitate in contacting us at:
 
-  GitHub: https://github.com/balena-io/balena-cli/issues/new
+  Forums: https://forums.balena.io
-  Forums: https://forums.balena.io\
+  GitHub: https://github.com/balena-io/balena-cli/issues/new\
 `;
 
 export const balenaAsciiArt = `\