improvements

Author: nieblara

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [Unreleased]
+
+### ⚠ BREAKING CHANGES
+
+* When stdout is not a TTY, the default `--output` format is now **json** instead of plaintext. Scripts that assumed plaintext when output was piped or redirected should set `LD_OUTPUT=plaintext`, run `ldcli config --set output plaintext`, or pass `--output plaintext` (or `--output json` explicitly if you want JSON regardless of TTY).
+
 ## [2.2.0](https://github.com/launchdarkly/ldcli/compare/v2.1.0...v2.2.0) (2026-02-20)
 
 

README.md

@@ -90,6 +90,14 @@ ldcli config --set access-token api-00000000-0000-0000-0000-000000000000
 
 Running this command creates a configuration file located at `$XDG_CONFIG_HOME/ldcli/config.yml` with the access token. Subsequent commands read from this file, so you do not need to specify the access token each time.
 
+### Output format defaults
+
+When you do not pass `--output` or `--json`, the default format depends on whether standard output is a terminal: **plaintext** in an interactive terminal, **json** when stdout is not a TTY (for example when piped, in CI, or in agent environments).
+
+To force the plaintext default even when stdout is not a TTY, set either **`FORCE_TTY`** or **`LD_FORCE_TTY`** to any non-empty value (similar to tools that use `NO_COLOR`). That only affects the default; explicit `--output`, `--json`, `LD_OUTPUT`, and the `output` setting in your config file still apply.
+
+Effective output is resolved in this order: **`--json`** and **`--output`** flags, then **`LD_OUTPUT`**, then the **`output`** value from your config file, then the TTY-based default above.
+
 ## Commands
 
 LaunchDarkly CLI commands:

cmd/cmdtest.go

@@ -19,6 +19,9 @@ var StubbedSuccessResponse = `{
 	"name": "test-name"
 }`
 
+// CallCmd runs the root command for integration-style tests. It passes isTerminal always true so
+// the default --output matches an interactive terminal (plaintext); non-TTY JSON defaults are
+// covered in root_test.go.
 func CallCmd(
 	t *testing.T,
 	clients APIClients,

cmd/root.go

@@ -82,6 +82,18 @@ func init() {
 	cobra.AddTemplateFunc("HasOptionalFlags", HasOptionalFlags)
 }
 
+// forceTTYDefaultOutput is true when FORCE_TTY or LD_FORCE_TTY is non-empty, so the default
+// --output is plaintext even if stdout is not a TTY (similar to NO_COLOR). Explicit --output,
+// --json, LD_OUTPUT, and config file values still take precedence via Viper/Cobra after parse.
+func forceTTYDefaultOutput() bool {
+	return os.Getenv("FORCE_TTY") != "" || os.Getenv("LD_FORCE_TTY") != ""
+}
+
+// NewRootCommand constructs the ldcli root command tree.
+//
+// isTerminal should reflect whether stdout is a TTY (see Execute). For nil or a function that
+// returns false, the default --output is json unless forceTTYDefaultOutput applies—intended for
+// tests and embeddings; production should always pass a non-nil detector.
 func NewRootCommand(
 	configService config.Service,
 	analyticsTrackerFn analytics.TrackerFn,
@@ -190,10 +202,10 @@ func NewRootCommand(
 		return nil, err
 	}
 
-	// When stdout is not a TTY (e.g. piped, CI, agent), default to JSON.
-	// FORCE_TTY: any non-empty value treats stdout as a terminal (like NO_COLOR convention).
+	// When stdout is not a TTY (e.g. piped, CI, agent), default to JSON unless FORCE_TTY or
+	// LD_FORCE_TTY is set (any non-empty value), like NO_COLOR.
 	defaultOutput := "plaintext"
-	if os.Getenv("FORCE_TTY") == "" && (isTerminal == nil || !isTerminal()) {
+	if !forceTTYDefaultOutput() && (isTerminal == nil || !isTerminal()) {
 		defaultOutput = "json"
 	}
 

cmd/root_test.go

@@ -4,8 +4,10 @@ import (
 	"bytes"
 	"io"
 	"os"
+	"path/filepath"
 	"testing"
 
+	"github.com/spf13/viper"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -153,12 +155,15 @@ func execNonTTYCmd(t *testing.T, mockClient *resources.MockClient, extraArgs ...
 	return out
 }
 
-func TestTTYDefaultOutput(t *testing.T) {
+func TestOutputDefaultsAndOverrides(t *testing.T) {
 	mockClient := &resources.MockClient{
 		Response: []byte(`{"key": "test-key", "name": "test-name"}`),
 	}
 
 	t.Run("non-TTY defaults to json output", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "")
+
 		rootCmd := newRootCmdWithTerminal(t, func() bool { return false })
 
 		f := rootCmd.Cmd().PersistentFlags().Lookup(cliflags.OutputFlag)
@@ -167,6 +172,9 @@ func TestTTYDefaultOutput(t *testing.T) {
 	})
 
 	t.Run("TTY defaults to plaintext output", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "")
+
 		rootCmd := newRootCmdWithTerminal(t, func() bool { return true })
 
 		f := rootCmd.Cmd().PersistentFlags().Lookup(cliflags.OutputFlag)
@@ -175,6 +183,9 @@ func TestTTYDefaultOutput(t *testing.T) {
 	})
 
 	t.Run("nil isTerminal defaults to json output", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "")
+
 		rootCmd := newRootCmdWithTerminal(t, nil)
 
 		f := rootCmd.Cmd().PersistentFlags().Lookup(cliflags.OutputFlag)
@@ -183,39 +194,125 @@ func TestTTYDefaultOutput(t *testing.T) {
 	})
 
 	t.Run("explicit --output plaintext overrides non-TTY", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "")
+
 		out := execNonTTYCmd(t, mockClient, "--output", "plaintext")
 		assert.Contains(t, string(out), "Successfully updated")
 	})
 
 	t.Run("non-TTY without explicit flag returns JSON", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "")
+
 		out := execNonTTYCmd(t, mockClient)
 		assert.Contains(t, string(out), `"key"`)
 		assert.NotContains(t, string(out), "Successfully updated")
 	})
 
 	t.Run("--json overrides non-TTY default", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "")
+
 		out := execNonTTYCmd(t, mockClient, "--json")
 		assert.Contains(t, string(out), `"key"`)
 		assert.NotContains(t, string(out), "Successfully updated")
 	})
 
 	t.Run("LD_OUTPUT=plaintext overrides non-TTY default", func(t *testing.T) {
-		os.Setenv("LD_OUTPUT", "plaintext")
-		defer os.Unsetenv("LD_OUTPUT")
+		t.Setenv("LD_OUTPUT", "plaintext")
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "")
 
 		out := execNonTTYCmd(t, mockClient)
 		assert.Contains(t, string(out), "Successfully updated")
 		assert.Contains(t, string(out), "test-name (test-key)")
 	})
 
-	t.Run("FORCE_TTY overrides non-TTY detection", func(t *testing.T) {
-		os.Setenv("FORCE_TTY", "1")
-		defer os.Unsetenv("FORCE_TTY")
+	t.Run("FORCE_TTY=0 yields plaintext DefValue when non-TTY", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "0")
+		t.Setenv("LD_FORCE_TTY", "")
 
 		rootCmd := newRootCmdWithTerminal(t, func() bool { return false })
 
 		f := rootCmd.Cmd().PersistentFlags().Lookup(cliflags.OutputFlag)
 		require.NotNil(t, f)
 		assert.Equal(t, "plaintext", f.DefValue)
 	})
+
+	t.Run("FORCE_TTY=1 yields plaintext DefValue when non-TTY", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "1")
+		t.Setenv("LD_FORCE_TTY", "")
+
+		rootCmd := newRootCmdWithTerminal(t, func() bool { return false })
+
+		f := rootCmd.Cmd().PersistentFlags().Lookup(cliflags.OutputFlag)
+		require.NotNil(t, f)
+		assert.Equal(t, "plaintext", f.DefValue)
+	})
+
+	t.Run("LD_FORCE_TTY=1 yields plaintext DefValue when non-TTY", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "1")
+
+		rootCmd := newRootCmdWithTerminal(t, func() bool { return false })
+
+		f := rootCmd.Cmd().PersistentFlags().Lookup(cliflags.OutputFlag)
+		require.NotNil(t, f)
+		assert.Equal(t, "plaintext", f.DefValue)
+	})
+
+	t.Run("LD_FORCE_TTY=1 yields plaintext output when non-TTY", func(t *testing.T) {
+		t.Setenv("FORCE_TTY", "")
+		t.Setenv("LD_FORCE_TTY", "1")
+
+		out := execNonTTYCmd(t, mockClient)
+		assert.Contains(t, string(out), "Successfully updated")
+		assert.Contains(t, string(out), "test-name (test-key)")
+	})
+}
+
+func TestConfigOutputPrecedenceNonTTY(t *testing.T) {
+	viper.Reset()
+	t.Cleanup(viper.Reset)
+
+	mockClient := &resources.MockClient{
+		Response: []byte(`{"key": "test-key", "name": "test-name"}`),
+	}
+
+	cfgRoot := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", cfgRoot)
+	t.Setenv("FORCE_TTY", "")
+	t.Setenv("LD_FORCE_TTY", "")
+
+	ldcliDir := filepath.Join(cfgRoot, "ldcli")
+	require.NoError(t, os.MkdirAll(ldcliDir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(ldcliDir, "config.yml"), []byte("output: plaintext\n"), 0o644))
+
+	rootCmd, err := cmd.NewRootCommand(
+		config.NewService(&resources.MockClient{}),
+		analytics.NoopClientFn{}.Tracker(),
+		cmd.APIClients{ResourcesClient: mockClient},
+		"test",
+		true,
+		func() bool { return false },
+	)
+	require.NoError(t, err)
+
+	c := rootCmd.Cmd()
+	b := bytes.NewBufferString("")
+	c.SetOut(b)
+	c.SetArgs([]string{
+		"flags", "toggle-on",
+		"--access-token", "abcd1234",
+		"--environment", "test-env",
+		"--flag", "test-flag",
+		"--project", "test-proj",
+	})
+	require.NoError(t, c.Execute())
+
+	out, err := io.ReadAll(b)
+	require.NoError(t, err)
+	assert.Contains(t, string(out), "Successfully updated")
+	assert.Contains(t, string(out), "test-name (test-key)")
 }