Remove yaml output format from --format flag. / Deprecate `--form…

…at json` in favor of `--json` (#2587)

* Removed 'yaml' output from '--format' flag

* Deprecated '--format json' in favor of '--json'

* Updated all --format json references to use --json

docs/UPGRADING.md

@@ -4,6 +4,10 @@ Here you can find a list of migration guides to handle breaking changes between
 
 ## 0.36.0
 
+### YAML output format is no more supported
+
+The `yaml` option of the `--format` flag is no more supported. Use `--format json` if machine parsable output is needed.
+
 ### The gRPC `cc.arduino.cli.commands.v1.CompileRequest.export_binaries` changed type.
 
 Previously the field `export_binaries` was a `google.protobuf.BoolValue`. We used this type because it expresses this

docs/getting-started.md

@@ -8,34 +8,35 @@ IDE. Let's see some examples.
 
 ```console
 $ arduino-cli help core
-Arduino Core operations.
+Arduino core operations.
 
 Usage:
-    arduino-cli core [command]
+  arduino-cli core [command]
 
 Examples:
-    ./arduino-cli core update-index
+  arduino-cli core update-index
 
 Available Commands:
-    download     Downloads one or more cores and corresponding tool dependencies.
-    install      Installs one or more cores and corresponding tool dependencies.
-    list         Shows the list of installed platforms.
-    search       Search for a core in Boards Manager.
-    uninstall    Uninstalls one or more cores and corresponding tool dependencies if no more used.
-    update-index Updates the index of cores.
-    upgrade      Upgrades one or all installed platforms to the latest version.
+  download     Downloads one or more cores and corresponding tool dependencies.
+  install      Installs one or more cores and corresponding tool dependencies.
+  list         Shows the list of installed platforms.
+  search       Search for a core in Boards Manager.
+  uninstall    Uninstalls one or more cores and corresponding tool dependencies if no longer used.
+  update-index Updates the index of cores.
+  upgrade      Upgrades one or all installed platforms to the latest version.
 
 Flags:
-    -h, --help   help for core
+  -h, --help   help for core
 
 Global Flags:
-        --additional-urls strings   Additional URLs for Boards Manager.
-        --config-file string        The custom config file (if not specified the default will be used).
-        --format string             The output format, can be [text|json]. (default "text")
-        --log-file string           Path to the file where logs will be written.
-        --log-format string         The output format for the logs, can be [text|json].
-        --log-level string          Messages with this level and above will be logged.
-    -v, --verbose                   Print the logs on the standard output.
+      --additional-urls strings   Comma-separated list of additional URLs for the Boards Manager.
+      --config-file string        The custom config file (if not specified the default will be used).
+      --json                      Print the output in JSON format.
+      --log                       Print the logs on the standard output.
+      --log-file string           Path to the file where logs will be written.
+      --log-format string         The output format for the logs, can be: text, json
+      --log-level string          Messages with this level and above will be logged. Valid levels are: trace, debug, info, warn, error, fatal, panic
+      --no-color                  Disable colored output.
 
 Use "arduino-cli core [command] --help" for more information about a command.
 ```

docs/versioning.md

@@ -45,8 +45,8 @@ The following changes to the command-line syntax are NOT considered breaking:
 Any change in the **human-readable** text output is **NOT** considered a breaking change. In general, the human-readable
 text is subject to translation and small adjustments in natural language syntax and presentation.
 
-We will consider breaking changes only in the **machine-readable** output of the commands using the `--format json`
-flag. In particular, we have a breaking change in the JSON command output if:
+We will consider breaking changes only in the **machine-readable** output of the commands using the `--json` flag. In
+particular, we have a breaking change in the JSON command output if:
 
 - a key in a JSON object is renamed or removed.
 - a value in a JSON object or array changes meaning or changes format.

go.mod

@@ -44,7 +44,6 @@ require (
 	google.golang.org/grpc v1.62.1
 	google.golang.org/protobuf v1.33.0
 	gopkg.in/yaml.v3 v3.0.1
-	sigs.k8s.io/yaml v1.4.0
 )
 
 require (

go.sum

@@ -82,7 +82,6 @@ github.com/golang/protobuf v1.5.3/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiu
 github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/h2non/filetype v1.1.3 h1:FKkx9QbD7HR/zjK1Ia5XiBsq9zdLi5Kf3zGyFTAFkGg=
@@ -300,5 +299,3 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-sigs.k8s.io/yaml v1.4.0 h1:Mk1wCc2gy/F0THH0TAp1QYyJNzRm2KCLy3o5ASXVI5E=
-sigs.k8s.io/yaml v1.4.0/go.mod h1:Ejl7/uTz7PSA4eKMyQCUTnhZYNmLIl+5c2lQPGR2BPY=

internal/cli/cli.go

@@ -58,6 +58,7 @@ import (
 
 var (
 	verbose      bool
+	jsonOutput   bool
 	outputFormat string
 	configFile   string
 )
@@ -75,6 +76,10 @@ func NewCommand() *cobra.Command {
 		Long:    tr("Arduino Command Line Interface (arduino-cli)."),
 		Example: fmt.Sprintf("  %s <%s> [%s...]", os.Args[0], tr("command"), tr("flags")),
 		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+			if jsonOutput {
+				outputFormat = "json"
+			}
+
 			preRun(cmd, args)
 
 			if cmd.Name() != "version" {
@@ -150,11 +155,13 @@ func createCliCommandTree(cmd *cobra.Command) {
 	cmd.RegisterFlagCompletionFunc("log-format", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return validLogFormats, cobra.ShellCompDirectiveDefault
 	})
-	validOutputFormats := []string{"text", "json", "jsonmini", "yaml"}
-	cmd.PersistentFlags().StringVar(&outputFormat, "format", "text", tr("The output format for the logs, can be: %s", strings.Join(validOutputFormats, ", ")))
+	validOutputFormats := []string{"text", "json", "jsonmini"}
+	cmd.PersistentFlags().StringVar(&outputFormat, "format", "text", tr("The command output format, can be: %s", strings.Join(validOutputFormats, ", ")))
 	cmd.RegisterFlagCompletionFunc("format", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return validOutputFormats, cobra.ShellCompDirectiveDefault
 	})
+	cmd.Flag("format").Hidden = true
+	cmd.PersistentFlags().BoolVar(&jsonOutput, "json", false, tr("Print the output in JSON format."))
 	cmd.PersistentFlags().StringVar(&configFile, "config-file", "", tr("The custom config file (if not specified the default will be used)."))
 	cmd.PersistentFlags().StringSlice("additional-urls", []string{}, tr("Comma-separated list of additional URLs for the Boards Manager."))
 	cmd.PersistentFlags().Bool("no-color", false, "Disable colored output.")

internal/cli/core/upgrade.go

@@ -142,7 +142,7 @@ func Upgrade(inst *rpc.Instance, args []string, skipPostInstall bool, skipPreUni
 	feedback.PrintResult(&platformUpgradeResult{})
 }
 
-// This is needed so we can print warning messages in case users use --format json
+// This is needed so we can print warning messages in case users use --json
 type platformUpgradeResult struct{}
 
 // Data implements feedback.Result.

internal/cli/feedback/feedback.go

@@ -26,7 +26,6 @@ import (
 
 	"github.com/arduino/arduino-cli/internal/i18n"
 	"github.com/sirupsen/logrus"
-	"sigs.k8s.io/yaml"
 )
 
 // OutputFormat is an output format
@@ -39,14 +38,11 @@ const (
 	JSON
 	// MinifiedJSON format
 	MinifiedJSON
-	// YAML format
-	YAML
 )
 
 var formats = map[string]OutputFormat{
 	"json":     JSON,
 	"jsonmini": MinifiedJSON,
-	"yaml":     YAML,
 	"text":     Text,
 }
 
@@ -204,8 +200,6 @@ func Fatal(errorMsg string, exitCode ExitCode) {
 		d, _ = json.MarshalIndent(augment(res), "", "  ")
 	case MinifiedJSON:
 		d, _ = json.Marshal(augment(res))
-	case YAML:
-		d, _ = yaml.Marshal(augment(res))
 	default:
 		panic("unknown output format")
 	}
@@ -250,12 +244,6 @@ func PrintResult(res Result) {
 			Fatal(tr("Error during JSON encoding of the output: %v", err), ErrGeneric)
 		}
 		data = string(d)
-	case YAML:
-		d, err := yaml.Marshal(augment(res.Data()))
-		if err != nil {
-			Fatal(tr("Error during YAML encoding of the output: %v", err), ErrGeneric)
-		}
-		data = string(d)
 	case Text:
 		data = res.String()
 		if resErr, ok := res.(ErrorResult); ok {

internal/integrationtest/arduino-cli.go

@@ -375,7 +375,7 @@ func (cli *ArduinoCLI) run(stdoutBuff, stderrBuff io.Writer, stdinBuff io.Reader
 
 // StartDaemon starts the Arduino CLI daemon. It returns the address of the daemon.
 func (cli *ArduinoCLI) StartDaemon(verbose bool) string {
-	args := []string{"daemon", "--format", "json"}
+	args := []string{"daemon", "--json"}
 	if cli.cliConfigPath != nil {
 		args = append([]string{"--config-file", cli.cliConfigPath.String()}, args...)
 	}

internal/integrationtest/board/board_test.go

@@ -36,7 +36,7 @@ func TestCorrectBoardListOrdering(t *testing.T) {
 	require.NoError(t, err)
 	_, _, err = cli.Run("core", "install", "arduino:avr")
 	require.NoError(t, err)
-	jsonOut, _, err := cli.Run("board", "listall", "--format", "json")
+	jsonOut, _, err := cli.Run("board", "listall", "--json")
 	require.NoError(t, err)
 	requirejson.Query(t, jsonOut, "[.boards[] | .fqbn]", `[
 		"arduino:avr:yun",
@@ -80,7 +80,7 @@ func TestBoardList(t *testing.T) {
 
 	cli.InstallMockedSerialDiscovery(t)
 
-	stdout, _, err := cli.Run("board", "list", "--format", "json")
+	stdout, _, err := cli.Run("board", "list", "--json")
 	require.NoError(t, err)
 	// check is a valid json and contains a list of ports
 	requirejson.Parse(t, stdout).
@@ -97,7 +97,7 @@ func TestBoardListMock(t *testing.T) {
 
 	cli.InstallMockedSerialDiscovery(t)
 
-	stdout, _, err := cli.Run("board", "list", "--format", "json")
+	stdout, _, err := cli.Run("board", "list", "--json")
 	require.NoError(t, err)
 
 	// check is a valid json and contains a list of ports
@@ -136,7 +136,7 @@ func TestBoardListWithFqbnFilter(t *testing.T) {
 
 	cli.InstallMockedSerialDiscovery(t)
 
-	stdout, _, err := cli.Run("board", "list", "-b", "foo:bar:baz", "--format", "json")
+	stdout, _, err := cli.Run("board", "list", "-b", "foo:bar:baz", "--json")
 	require.NoError(t, err)
 	requirejson.Query(t, stdout, `.detected_ports | length`, `0`)
 }
@@ -150,7 +150,7 @@ func TestBoardListWithFqbnFilterInvalid(t *testing.T) {
 
 	cli.InstallMockedSerialDiscovery(t)
 
-	_, stderr, err := cli.Run("board", "list", "-b", "yadayada", "--format", "json")
+	_, stderr, err := cli.Run("board", "list", "-b", "yadayada", "--json")
 	require.Error(t, err)
 	requirejson.Query(t, stderr, ".error", `"Invalid FQBN: not an FQBN: yadayada"`)
 }
@@ -164,7 +164,7 @@ func TestBoardListall(t *testing.T) {
 	_, _, err = cli.Run("core", "install", "arduino:avr@1.8.3")
 	require.NoError(t, err)
 
-	stdout, _, err := cli.Run("board", "listall", "--format", "json")
+	stdout, _, err := cli.Run("board", "listall", "--json")
 	require.NoError(t, err)
 
 	requirejson.Query(t, stdout, ".boards | length", "26")
@@ -224,7 +224,7 @@ func TestBoardListallWithManuallyInstalledPlatform(t *testing.T) {
 	})
 	require.NoError(t, err)
 
-	stdout, _, err := cli.Run("board", "listall", "--format", "json")
+	stdout, _, err := cli.Run("board", "listall", "--json")
 	require.NoError(t, err)
 
 	requirejson.Query(t, stdout, ".boards | length", "17")
@@ -274,11 +274,11 @@ func TestBoardDetails(t *testing.T) {
 	require.NoError(t, err)
 
 	// Test board listall with and without showing hidden elements
-	stdout, _, err := cli.Run("board", "listall", "MIPS", "--format", "json")
+	stdout, _, err := cli.Run("board", "listall", "MIPS", "--json")
 	require.NoError(t, err)
 	require.Equal(t, string(stdout), "{}\n")
 
-	stdout, _, err = cli.Run("board", "listall", "MIPS", "-a", "--format", "json")
+	stdout, _, err = cli.Run("board", "listall", "MIPS", "-a", "--json")
 	require.NoError(t, err)
 	requirejson.Contains(t, stdout, `{
 		"boards": [
@@ -288,7 +288,7 @@ func TestBoardDetails(t *testing.T) {
 		]
 	}`)
 
-	stdout, _, err = cli.Run("board", "details", "-b", "arduino:samd:nano_33_iot", "--format", "json")
+	stdout, _, err = cli.Run("board", "details", "-b", "arduino:samd:nano_33_iot", "--json")
 	require.NoError(t, err)
 
 	requirejson.Contains(t, stdout, `{
@@ -425,7 +425,7 @@ func TestBoardSearch(t *testing.T) {
 	_, _, err := cli.Run("update")
 	require.NoError(t, err)
 
-	stdout, _, err := cli.Run("board", "search", "--format", "json")
+	stdout, _, err := cli.Run("board", "search", "--json")
 	require.NoError(t, err)
 	// Verifies boards are returned
 	requirejson.NotEmpty(t, stdout)
@@ -441,7 +441,7 @@ func TestBoardSearch(t *testing.T) {
 		]}`)
 
 	// Search in non installed boards
-	stdout, _, err = cli.Run("board", "search", "--format", "json", "nano", "33")
+	stdout, _, err = cli.Run("board", "search", "--json", "nano", "33")
 	require.NoError(t, err)
 	// Verifies boards are returned
 	requirejson.NotEmpty(t, stdout)
@@ -457,7 +457,7 @@ func TestBoardSearch(t *testing.T) {
 	_, _, err = cli.Run("core", "install", "arduino:avr@1.8.3")
 	require.NoError(t, err)
 
-	stdout, _, err = cli.Run("board", "search", "--format", "json")
+	stdout, _, err = cli.Run("board", "search", "--json")
 	require.NoError(t, err)
 	requirejson.NotEmpty(t, stdout)
 	// Verifies some FQBNs are now returned after installing a platform
@@ -474,7 +474,7 @@ func TestBoardSearch(t *testing.T) {
 			}
 		]}`)
 
-	stdout, _, err = cli.Run("board", "search", "--format", "json", "arduino", "yun")
+	stdout, _, err = cli.Run("board", "search", "--json", "arduino", "yun")
 	require.NoError(t, err)
 	requirejson.NotEmpty(t, stdout)
 	requirejson.Contains(t, stdout, `{
@@ -494,7 +494,7 @@ func TestBoardSearch(t *testing.T) {
 	})
 	require.NoError(t, err)
 
-	stdout, _, err = cli.Run("board", "search", "--format", "json")
+	stdout, _, err = cli.Run("board", "search", "--json")
 	require.NoError(t, err)
 	requirejson.NotEmpty(t, stdout)
 	// Verifies some FQBNs are now returned after installing a platform
@@ -531,7 +531,7 @@ func TestBoardSearch(t *testing.T) {
 			}
 		]}`)
 
-	stdout, _, err = cli.Run("board", "search", "--format", "json", "mkr1000")
+	stdout, _, err = cli.Run("board", "search", "--json", "mkr1000")
 	require.NoError(t, err)
 	requirejson.NotEmpty(t, stdout)
 	// Verifies some FQBNs are now returned after installing a platform
@@ -557,7 +557,7 @@ func TestBoardAttach(t *testing.T) {
 	require.NoError(t, err)
 
 	{
-		stdout, _, err := cli.Run("board", "attach", "-b", "arduino:avr:uno", sketchPath.String(), "--format", "json")
+		stdout, _, err := cli.Run("board", "attach", "-b", "arduino:avr:uno", sketchPath.String(), "--json")
 		require.NoError(t, err)
 		requirejson.Query(t, stdout, ".fqbn", `"arduino:avr:uno"`)
 
@@ -568,7 +568,7 @@ func TestBoardAttach(t *testing.T) {
 		require.NotContains(t, string(yamlData), "default_protocol:")
 	}
 	{
-		stdout, _, err := cli.Run("board", "attach", "-p", "/dev/ttyACM0", "-l", "serial", sketchPath.String(), "--format", "json")
+		stdout, _, err := cli.Run("board", "attach", "-p", "/dev/ttyACM0", "-l", "serial", sketchPath.String(), "--json")
 		require.NoError(t, err)
 		requirejson.Query(t, stdout, ".fqbn", `"arduino:avr:uno"`)
 		requirejson.Query(t, stdout, ".port.address", `"/dev/ttyACM0"`)
@@ -581,7 +581,7 @@ func TestBoardAttach(t *testing.T) {
 		require.Contains(t, string(yamlData), "default_protocol: serial")
 	}
 	{
-		stdout, _, err := cli.Run("board", "attach", "-p", "/dev/ttyACM0", sketchPath.String(), "--format", "json")
+		stdout, _, err := cli.Run("board", "attach", "-p", "/dev/ttyACM0", sketchPath.String(), "--json")
 		require.NoError(t, err)
 		requirejson.Query(t, stdout, ".fqbn", `"arduino:avr:uno"`)
 		requirejson.Query(t, stdout, ".port.address", `"/dev/ttyACM0"`)
@@ -594,7 +594,7 @@ func TestBoardAttach(t *testing.T) {
 		require.NotContains(t, string(yamlData), "default_protocol:")
 	}
 	{
-		stdout, _, err := cli.Run("board", "attach", "-b", "arduino:samd:mkr1000", "-P", "atmel_ice", sketchPath.String(), "--format", "json")
+		stdout, _, err := cli.Run("board", "attach", "-b", "arduino:samd:mkr1000", "-P", "atmel_ice", sketchPath.String(), "--json")
 		require.NoError(t, err)
 		requirejson.Query(t, stdout, ".fqbn", `"arduino:samd:mkr1000"`)
 		requirejson.Query(t, stdout, ".programmer", `"atmel_ice"`)