feat: add --dry-run flag to toggle-on, toggle-off, and archive commands (#677)

* adding agent flag for agent telemtry

* (feat) adding TTY detection for auto-JSON output

* improvements

* addressing pr feedback

* feat(REL-12754): Agent friendly error handling (#661)

* [feat] Agent friendly error handling

* feat(REL-12755): adding --fields flag (#662)

* [feat] adding --fields flag

* feat(REL-15756): updating agent friendly and improved rich text output (#663)

feat(REL-15756) updating agent friendly and improved rich text output

* fix: update stale test assertions for key-value plaintext format

Three tests in root_test.go still asserted the old `name (key)` bullet
format, but the toggle-on command now passes ResourceName: "flags" which
triggers key-value output. Update to match the actual output shape.

Made-with: Cursor

* refactor: move fields into CmdOutputOpts, warn on plaintext --fields

Remove the standalone `fields []string` positional parameter from
CmdOutput and pass fields exclusively through CmdOutputOpts.Fields.
This eliminates the dual-path API and simplifies every call site.

Also emit a stderr warning when --fields is used with plaintext output,
since the flag is silently ignored in that mode.

Made-with: Cursor

* docs: document error shape and table format breaking changes in CHANGELOG

Add entries for the error JSON shape change (new statusCode/suggestion
fields, message casing) and the plaintext table format change. Both are
breaking changes that should be called out for v3.0.

Made-with: Cursor

* feat: add --dry-run flag to toggle-on, toggle-off, and archive commands

The API already supports dryRun as a query parameter on PATCH
/api/v2/flags. The auto-generated `flags update` command exposes it,
but the hand-rolled toggle and archive commands passed nil for query
params. This wires --dry-run through to MakeRequest on all three.

Also adds a Query field to MockClient so tests can verify query params.

Made-with: Cursor

* fix: use toggle-off in TestToggleOff dry-run tests

Copy-paste error had both dry-run subtests invoking toggle-on instead
of toggle-off, so toggle-off's --dry-run path was never exercised.

Made-with: Cursor

Author: nieblara

cmd/cliflags/flags.go

@@ -33,6 +33,7 @@ const (
 	CorsEnabledFlag  = "cors-enabled"
 	CorsOriginFlag   = "cors-origin"
 	DataFlag         = "data"
+	DryRunFlag       = "dry-run"
 	DevStreamURIFlag = "dev-stream-uri"
 	EmailsFlag       = "emails"
 	EnvironmentFlag  = "environment"
@@ -51,6 +52,7 @@ const (
 	CorsEnabledFlagDescription = "Enable CORS headers for browser-based developer tools (default: false)"
 	CorsOriginFlagDescription  = "Allowed CORS origin. Use '*' for all origins (default: '*')"
 	DevStreamURIDescription    = "Streaming service endpoint that the dev server uses to obtain authoritative flag data. This may be a LaunchDarkly or Relay Proxy endpoint"
+	DryRunFlagDescription      = "Validate the change without persisting it. Returns a preview of the result."
 	EnvironmentFlagDescription = "Default environment key"
 	FieldsFlagDescription      = "Comma-separated list of top-level fields to include in JSON output (e.g., --fields key,name,kind)"
 	FlagFlagDescription        = "Default feature flag key"

cmd/flags/archive.go

@@ -38,12 +38,16 @@ func makeArchiveRequest(client resources.Client) func(*cobra.Command, []string)
 			viper.GetString(cliflags.ProjectFlag),
 			viper.GetString(cliflags.FlagFlag),
 		)
+		var query url.Values
+		if dryRun, _ := cmd.Flags().GetBool(cliflags.DryRunFlag); dryRun {
+			query = url.Values{"dryRun": []string{"true"}}
+		}
 		res, err := client.MakeRequest(
 			viper.GetString(cliflags.AccessTokenFlag),
 			"PATCH",
 			path,
 			"application/json",
-			nil,
+			query,
 			[]byte(`[{"op": "replace", "path": "/archived", "value": true}]`),
 			false,
 		)
@@ -75,4 +79,6 @@ func initArchiveFlags(cmd *cobra.Command) {
 	_ = cmd.MarkFlagRequired(cliflags.ProjectFlag)
 	_ = cmd.Flags().SetAnnotation(cliflags.ProjectFlag, "required", []string{"true"})
 	_ = viper.BindPFlag(cliflags.ProjectFlag, cmd.Flags().Lookup(cliflags.ProjectFlag))
+
+	cmd.Flags().Bool(cliflags.DryRunFlag, false, cliflags.DryRunFlagDescription)
 }

cmd/flags/archive_test.go

@@ -155,6 +155,49 @@ func TestArchive(t *testing.T) {
 		assert.Contains(t, string(output), "test-flag")
 	})
 
+	t.Run("passes dryRun query param when --dry-run is set", func(t *testing.T) {
+		args := []string{
+			"flags", "archive",
+			"--access-token", "abcd1234",
+			"--flag", "test-flag",
+			"--project", "test-proj",
+			"--output", "json",
+			"--dry-run",
+		}
+		_, err := cmd.CallCmd(
+			t,
+			cmd.APIClients{
+				ResourcesClient: mockClient,
+			},
+			analytics.NoopClientFn{}.Tracker(),
+			args,
+		)
+
+		require.NoError(t, err)
+		assert.Equal(t, "true", mockClient.Query.Get("dryRun"))
+	})
+
+	t.Run("does not pass dryRun query param by default", func(t *testing.T) {
+		args := []string{
+			"flags", "archive",
+			"--access-token", "abcd1234",
+			"--flag", "test-flag",
+			"--project", "test-proj",
+			"--output", "json",
+		}
+		_, err := cmd.CallCmd(
+			t,
+			cmd.APIClients{
+				ResourcesClient: mockClient,
+			},
+			analytics.NoopClientFn{}.Tracker(),
+			args,
+		)
+
+		require.NoError(t, err)
+		assert.Empty(t, mockClient.Query.Get("dryRun"))
+	})
+
 	t.Run("returns error with missing flags", func(t *testing.T) {
 		args := []string{
 			"flags", "archive",

cmd/flags/toggle.go

@@ -60,12 +60,16 @@ func runE(client resources.Client) func(*cobra.Command, []string) error {
 			viper.GetString(cliflags.ProjectFlag),
 			viper.GetString(cliflags.FlagFlag),
 		)
+		var query url.Values
+		if dryRun, _ := cmd.Flags().GetBool(cliflags.DryRunFlag); dryRun {
+			query = url.Values{"dryRun": []string{"true"}}
+		}
 		res, err := client.MakeRequest(
 			viper.GetString(cliflags.AccessTokenFlag),
 			"PATCH",
 			path,
 			"application/json",
-			nil,
+			query,
 			[]byte(buildPatch(viper.GetString("environment"), toggleOn)),
 			false,
 		)
@@ -102,6 +106,8 @@ func initFlags(cmd *cobra.Command) {
 	_ = cmd.MarkFlagRequired(cliflags.ProjectFlag)
 	_ = cmd.Flags().SetAnnotation(cliflags.ProjectFlag, "required", []string{"true"})
 	_ = viper.BindPFlag(cliflags.ProjectFlag, cmd.Flags().Lookup(cliflags.ProjectFlag))
+
+	cmd.Flags().Bool(cliflags.DryRunFlag, false, cliflags.DryRunFlagDescription)
 }
 
 func buildPatch(envKey string, toggleValue bool) string {

cmd/flags/toggle_test.go

@@ -332,6 +332,51 @@ func TestToggleOff(t *testing.T) {
 		assert.Contains(t, string(output), "test-flag")
 	})
 
+	t.Run("passes dryRun query param when --dry-run is set", func(t *testing.T) {
+		args := []string{
+			"flags", "toggle-off",
+			"--access-token", "abcd1234",
+			"--environment", "test-env",
+			"--flag", "test-flag",
+			"--project", "test-proj",
+			"--output", "json",
+			"--dry-run",
+		}
+		_, err := cmd.CallCmd(
+			t,
+			cmd.APIClients{
+				ResourcesClient: mockClient,
+			},
+			analytics.NoopClientFn{}.Tracker(),
+			args,
+		)
+
+		require.NoError(t, err)
+		assert.Equal(t, "true", mockClient.Query.Get("dryRun"))
+	})
+
+	t.Run("does not pass dryRun query param by default", func(t *testing.T) {
+		args := []string{
+			"flags", "toggle-off",
+			"--access-token", "abcd1234",
+			"--environment", "test-env",
+			"--flag", "test-flag",
+			"--project", "test-proj",
+			"--output", "json",
+		}
+		_, err := cmd.CallCmd(
+			t,
+			cmd.APIClients{
+				ResourcesClient: mockClient,
+			},
+			analytics.NoopClientFn{}.Tracker(),
+			args,
+		)
+
+		require.NoError(t, err)
+		assert.Empty(t, mockClient.Query.Get("dryRun"))
+	})
+
 	t.Run("returns error with missing required flags", func(t *testing.T) {
 		args := []string{
 			"flags", "toggle-off",

internal/resources/mock_client.go

@@ -8,6 +8,7 @@ import (
 type MockClient struct {
 	Err        error
 	Input      []byte
+	Query      url.Values
 	Response   []byte
 	StatusCode int
 }
@@ -21,6 +22,7 @@ func (c *MockClient) MakeRequest(
 	isBeta bool,
 ) ([]byte, error) {
 	c.Input = data
+	c.Query = query
 
 	if c.StatusCode > http.StatusBadRequest {
 		return c.Response, c.Err