diff --git a/pkg/cli/env_command.go b/pkg/cli/env_command.go
index 3cc7ffe69e6..c3aeac44c38 100644
--- a/pkg/cli/env_command.go
+++ b/pkg/cli/env_command.go
@@ -133,7 +133,16 @@ func newDefaultsGetCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "get [file]",
 		Short: "Download defaults into a YAML file",
-		Args:  cobra.MaximumNArgs(1),
+		Long: `Download compiler defaults into a YAML file.
+
+When [file] is omitted, the command writes to file.yml.
+
+Scope resolution:
+- --scope defaults to repo.
+- repo scope uses --repo owner/repo, or the current repository when --repo is omitted.
+- org scope uses --org when provided; otherwise it infers the organization from --repo (or the current repository).
+- ent scope requires --enterprise <slug>.`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			outputFile := "file.yml"
 			if len(args) == 1 {
@@ -161,7 +170,18 @@ func newDefaultsUpdateCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update [file]",
 		Short: "Upload defaults from a YAML file",
-		Args:  cobra.MaximumNArgs(1),
+		Long: `Upload compiler defaults from a YAML file.
+
+When [file] is omitted, the command reads from file.yml.
+
+Scope and flag behavior:
+- --scope is required (repo|org|ent).
+- repo scope uses --repo owner/repo, or the current repository when --repo is omitted.
+- org scope uses --org when provided; otherwise it infers the organization from --repo (or the current repository).
+- ent scope requires --enterprise <slug>.
+- --dry-run previews planned changes and exits without applying updates.
+- --yes skips the confirmation prompt for real updates; it has no effect with --dry-run.`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			inputFile := "file.yml"
 			if len(args) == 1 {
diff --git a/pkg/cli/env_command_test.go b/pkg/cli/env_command_test.go
index a14d42ebd7e..76377d108db 100644
--- a/pkg/cli/env_command_test.go
+++ b/pkg/cli/env_command_test.go
@@ -16,11 +16,12 @@ func TestNewEnvCommand(t *testing.T) {
 	require.NotNil(t, cmd)
 	assert.Equal(t, "env", cmd.Use)
 
-	var updateCmd *cobra.Command
+	var getCmd, updateCmd *cobra.Command
 	var hasGet, hasUpdate bool
 	for _, sub := range cmd.Commands() {
 		if sub.Name() == "get" {
 			hasGet = true
+			getCmd = sub
 		}
 		if sub.Name() == "update" {
 			hasUpdate = true
@@ -29,7 +30,17 @@ func TestNewEnvCommand(t *testing.T) {
 	}
 	assert.True(t, hasGet, "env command should include get subcommand")
 	assert.True(t, hasUpdate, "env command should include update subcommand")
+	require.NotNil(t, getCmd)
 	require.NotNil(t, updateCmd)
+	assert.NotEmpty(t, getCmd.Long)
+	assert.Contains(t, getCmd.Long, "file")
+	assert.Contains(t, getCmd.Long, "scope")
+	assert.Contains(t, getCmd.Long, "--enterprise")
+	assert.NotEmpty(t, updateCmd.Long)
+	assert.Contains(t, updateCmd.Long, "file")
+	assert.Contains(t, updateCmd.Long, "scope")
+	assert.Contains(t, updateCmd.Long, "--dry-run")
+	assert.Contains(t, updateCmd.Long, "--yes")
 	assert.NotNil(t, updateCmd.Flags().Lookup("yes"))
 	assert.NotNil(t, updateCmd.Flags().Lookup("dry-run"))
 }