feat(REL-12752): adding TTY detection for auto-JSON output

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). You can also set **`FORCE_TTY`** or **`LD_FORCE_TTY`** to any non-empty value to keep plaintext as the default when stdout is not a TTY, without changing the saved `output` setting.
+
 ## [2.2.0](https://github.com/launchdarkly/ldcli/compare/v2.1.0...v2.2.0) (2026-02-20)
 
 

README.md

@@ -67,7 +67,7 @@ Supported settings:
 * `base-uri` LaunchDarkly base URI (default "https://app.launchdarkly.com")
 - `environment`: Default environment key
 - `flag`: Default feature flag key
-- `output`: Command response output format in either JSON or plain text
+- `output`: Output format: json or plaintext (default: plaintext in a terminal, json otherwise)
 - `project`: Default project key
 
 Available `config` commands:
@@ -90,6 +90,16 @@ 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.
+
+**`LD_OUTPUT`** is the same setting as `output` in the config file, exposed as an environment variable (see the `LD_` prefix above). It is not new with TTY detection; the test suite locks in that it overrides the non-TTY JSON default when set to `plaintext`.
+
+Effective output is resolved in this order: **`--json`** (if set, wins over `--output` when both are present), then **`--output`**, then **`LD_OUTPUT`**, then the **`output`** value from your config file, then the TTY-based default above.
+
 ## Commands
 
 LaunchDarkly CLI commands:

cmd/analytics/analytics_test.go

@@ -8,8 +8,8 @@ import (
 )
 
 type mockEnvChecker struct {
-	envVars       map[string]string
-	stdinTerminal bool
+	envVars        map[string]string
+	stdinTerminal  bool
 	stdoutTerminal bool
 }
 

cmd/cliflags/flags.go

@@ -44,7 +44,7 @@ const (
 	EnvironmentFlagDescription = "Default environment key"
 	FlagFlagDescription        = "Default feature flag key"
 	JSONFlagDescription        = "Output JSON format (shorthand for --output json)"
-	OutputFlagDescription      = "Command response output format in either JSON or plain text"
+	OutputFlagDescription      = "Output format: json or plaintext (default: plaintext in a terminal, json otherwise)"
 	PortFlagDescription        = "Port for the dev server to run on"
 	ProjectFlagDescription     = "Default project key"
 	SyncOnceFlagDescription    = "Only sync new projects. Existing projects will neither be resynced nor have overrides specified by CLI flags applied."

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,
@@ -31,6 +34,8 @@ func CallCmd(
 		clients,
 		"test",
 		false,
+		func() bool { return true },
+		nil,
 	)
 	cmd := rootCmd.Cmd()
 	require.NoError(t, err)

cmd/config/testdata/help.golden

@@ -9,7 +9,7 @@ Supported settings:
 - `dev-stream-uri`: Streaming service endpoint that the dev server uses to obtain authoritative flag data. This may be a LaunchDarkly or Relay Proxy endpoint
 - `environment`: Default environment key
 - `flag`: Default feature flag key
-- `output`: Command response output format in either JSON or plain text
+- `output`: Output format: json or plaintext (default: plaintext in a terminal, json otherwise)
 - `port`: Port for the dev server to run on
 - `project`: Default project key
 - `sync-once`: Only sync new projects. Existing projects will neither be resynced nor have overrides specified by CLI flags applied.
@@ -28,4 +28,4 @@ Global Flags:
       --analytics-opt-out     Opt out of analytics tracking
       --base-uri string       LaunchDarkly base URI (default "https://app.launchdarkly.com")
       --json                  Output JSON format (shorthand for --output json)
-  -o, --output string         Command response output format in either JSON or plain text (default "plaintext")
+  -o, --output string         Output format: json or plaintext (default: plaintext in a terminal, json otherwise) (default "plaintext")

cmd/root.go

@@ -13,6 +13,7 @@ import (
 	"github.com/google/uuid"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
+	"golang.org/x/term"
 
 	cmdAnalytics "github.com/launchdarkly/ldcli/cmd/analytics"
 	"github.com/launchdarkly/ldcli/cmd/cliflags"
@@ -81,13 +82,40 @@ 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.
+//
+// getenv, if non-nil, is used only for those two keys (tests can inject without mutating
+// process environment). If nil, os.Getenv is used.
+func forceTTYDefaultOutput(getenv func(string) string) bool {
+	lookup := getenv
+	if lookup == nil {
+		lookup = os.Getenv
+	}
+	return lookup("FORCE_TTY") != "" || lookup("LD_FORCE_TTY") != ""
+}
+
+// NewRootCommand constructs the ldcli root command tree.
+//
+// isTerminal must be non-nil; it should reflect whether stdout is a TTY (see Execute). When it
+// returns false, the default --output is json unless forceTTYDefaultOutput applies.
+//
+// getenv is optional: when non-nil, it is used to read FORCE_TTY and LD_FORCE_TTY only; when
+// nil, os.Getenv is used. Viper still reads LD_OUTPUT and other LD_ vars from the real
+// environment.
 func NewRootCommand(
 	configService config.Service,
 	analyticsTrackerFn analytics.TrackerFn,
 	clients APIClients,
 	version string,
 	useConfigFile bool,
+	isTerminal func() bool,
+	getenv func(string) string,
 ) (*RootCmd, error) {
+	if isTerminal == nil {
+		return nil, errors.New("NewRootCommand: isTerminal must not be nil")
+	}
 	cmd := &cobra.Command{
 		Use:     "ldcli",
 		Short:   "LaunchDarkly CLI",
@@ -188,10 +216,17 @@ func NewRootCommand(
 		return nil, err
 	}
 
+	// 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 !forceTTYDefaultOutput(getenv) && !isTerminal() {
+		defaultOutput = "json"
+	}
+
 	cmd.PersistentFlags().StringP(
 		cliflags.OutputFlag,
 		"o",
-		"plaintext",
+		defaultOutput,
 		cliflags.OutputFlagDescription,
 	)
 	err = viper.BindPFlag(cliflags.OutputFlag, cmd.PersistentFlags().Lookup(cliflags.OutputFlag))
@@ -252,6 +287,8 @@ func Execute(version string) {
 		clients,
 		version,
 		true,
+		func() bool { return term.IsTerminal(int(os.Stdout.Fd())) },
+		nil,
 	)
 	if err != nil {
 		log.Fatal(err)