Merge remote-tracking branch 'origin/master' into copilot/featurereadable-toml-output

# Conflicts: # pkg/yqlib/toml_test.go Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>
2026-06-30 17:21:42 +00:00 · 2026-04-12 04:33:27 +00:00 · 2026-04-12 04:33:27 +00:00 · a297c15eb5
commit a297c15eb5
parent 3cba9952db c47fe40a30
17 changed files with 472 additions and 26 deletions
--- a/2
+++ b/2
@ -1,4 +1,4 @@
-FROM golang:1.26.1 AS builder
+FROM golang:1.26.2 AS builder

 WORKDIR /go/src/mikefarah/yq

--- a/Dockerfile.dev
+++ b/Dockerfile.dev
@ -1,4 +1,4 @@
-FROM golang:1.26.1
+FROM golang:1.26.2

 RUN apt-get update && \
    apt-get install -y npm && \
--- a/cmd/root.go
+++ b/cmd/root.go
@ -212,6 +212,7 @@ yq -P -oy sample.json

 	rootCmd.PersistentFlags().BoolVarP(&yqlib.ConfiguredSecurityPreferences.DisableEnvOps, "security-disable-env-ops", "", false, "Disable env related operations.")
 	rootCmd.PersistentFlags().BoolVarP(&yqlib.ConfiguredSecurityPreferences.DisableFileOps, "security-disable-file-ops", "", false, "Disable file related operations (e.g. load)")
+	rootCmd.PersistentFlags().BoolVarP(&yqlib.ConfiguredSecurityPreferences.EnableSystemOps, "security-enable-system-operator", "", false, "Enable system operator to allow execution of external commands.")

 	rootCmd.AddCommand(
 		createEvaluateSequenceCommand(),
--- a/go.mod
+++ b/go.mod
@ -19,7 +19,7 @@ require (
 	github.com/spf13/pflag v1.0.10
 	github.com/yuin/gopher-lua v1.1.2
 	github.com/zclconf/go-cty v1.18.0
-	go.yaml.in/yaml/v4 v4.0.0-rc.3
+	go.yaml.in/yaml/v4 v4.0.0-rc.4
 	golang.org/x/mod v0.34.0
 	golang.org/x/net v0.52.0
 	golang.org/x/text v0.35.0
--- a/go.sum
+++ b/go.sum
@ -68,8 +68,8 @@ github.com/zclconf/go-cty v1.18.0/go.mod h1:qpnV6EDNgC1sns/AleL1fvatHw72j+S+nS+M
 github.com/zclconf/go-cty-debug v0.0.0-20240509010212-0d6042c53940 h1:4r45xpDWB6ZMSMNJFMOjqrGHynW3DIBuR2H9j0ug+Mo=
 github.com/zclconf/go-cty-debug v0.0.0-20240509010212-0d6042c53940/go.mod h1:CmBdvvj3nqzfzJ6nTCIwDTPZ56aVGvDrmztiO5g3qrM=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-go.yaml.in/yaml/v4 v4.0.0-rc.3 h1:3h1fjsh1CTAPjW7q/EMe+C8shx5d8ctzZTrLcs/j8Go=
-go.yaml.in/yaml/v4 v4.0.0-rc.3/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
+go.yaml.in/yaml/v4 v4.0.0-rc.4 h1:UP4+v6fFrBIb1l934bDl//mmnoIZEDK0idg1+AIvX5U=
+go.yaml.in/yaml/v4 v4.0.0-rc.4/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
 golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
 golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
--- a/pkg/yqlib/doc/operators/headers/system-operators.md
+++ b/pkg/yqlib/doc/operators/headers/system-operators.md
@ -0,0 +1,27 @@
+# System Operators
+
+The `system` operator allows you to run an external command and use its output as a value in your expression.
+
+**Security warning**: The system operator is disabled by default. You must explicitly pass `--security-enable-system-operator` to use it.
+
+**Note:** When enabled, the system operator can replicate the functionality of `env` and `load`
+operators via external commands. Enabling it effectively overrides `--security-disable-env-ops`
+and `--security-disable-file-ops`.
+
+## Usage
+
+```bash
+yq --security-enable-system-operator --null-input '.field = system("command"; "arg1")'
+```
+
+The operator takes:
+- A command string (required)
+- An argument (or an array of arguments), separated from the command by `;` (optional)
+
+The current matched node's value is serialised and piped to the command via stdin. The command's stdout (with trailing newline stripped) is returned as a string.
+
+## Disabling the system operator
+
+The system operator is disabled by default. When disabled, an error is returned instead of running the command, consistent with `--security-disable-env-ops` and `--security-disable-file-ops`.
+
+Use `--security-enable-system-operator` flag to enable it.
--- a/pkg/yqlib/doc/operators/system-operators.md
+++ b/pkg/yqlib/doc/operators/system-operators.md
@ -0,0 +1,76 @@
+# System Operators
+
+The `system` operator allows you to run an external command and use its output as a value in your expression.
+
+**Security warning**: The system operator is disabled by default. You must explicitly pass `--security-enable-system-operator` to use it.
+
+**Note:** When enabled, the system operator can replicate the functionality of `env` and `load`
+operators via external commands. Enabling it effectively overrides `--security-disable-env-ops`
+and `--security-disable-file-ops`.
+
+## Usage
+
+```bash
+yq --security-enable-system-operator --null-input '.field = system("command"; "arg1")'
+```
+
+The operator takes:
+- A command string (required)
+- An argument (or an array of arguments), separated from the command by `;` (optional)
+
+The current matched node's value is serialised and piped to the command via stdin. The command's stdout (with trailing newline stripped) is returned as a string.
+
+## Disabling the system operator
+
+The system operator is disabled by default. When disabled, an error is returned instead of running the command, consistent with `--security-disable-env-ops` and `--security-disable-file-ops`.
+
+Use `--security-enable-system-operator` flag to enable it.
+
+## system operator returns error when disabled
+Use `--security-enable-system-operator` to enable the system operator.
+
+Given a sample.yml file of:
+```yaml
+country: Australia
+```
+then
+```bash
+yq '.country = system("/usr/bin/echo"; "test")' sample.yml
+```
+will output
+```bash
+Error: system operations are disabled, use --security-enable-system-operator to enable
+```
+
+## Run a command with an argument
+Use `--security-enable-system-operator` to enable the system operator.
+
+Given a sample.yml file of:
+```yaml
+country: Australia
+```
+then
+```bash
+yq --security-enable-system-operator '.country = system("/usr/bin/echo"; "test")' sample.yml
+```
+will output
+```yaml
+country: test
+```
+
+## Run a command without arguments
+Omit the semicolon and args to run the command with no extra arguments.
+
+Given a sample.yml file of:
+```yaml
+a: hello
+```
+then
+```bash
+yq --security-enable-system-operator '.a = system("/usr/bin/echo")' sample.yml
+```
+will output
+```yaml
+a: ""
+```
+
--- a/pkg/yqlib/encoder_toml.go
+++ b/pkg/yqlib/encoder_toml.go
@ -69,6 +69,27 @@ func (te *tomlEncoder) CanHandleAliases() bool {

 // ---- helpers ----

+// tomlKey returns the key quoted if it contains characters that are not valid
+// in a TOML bare key. TOML bare keys may only contain ASCII letters, ASCII
+// digits, underscores, and dashes.
+func tomlKey(key string) string {
+	for _, r := range key {
+		if (r < 'A' || r > 'Z') && (r < 'a' || r > 'z') && (r < '0' || r > '9') && r != '_' && r != '-' {
+			return fmt.Sprintf("%q", key)
+		}
+	}
+	return key
+}
+
+// tomlDottedKey joins path components, quoting any that require it.
+func tomlDottedKey(path []string) string {
+	parts := make([]string, len(path))
+	for i, p := range path {
+		parts[i] = tomlKey(p)
+	}
+	return strings.Join(parts, ".")
+}
+
 func (te *tomlEncoder) writeComment(w io.Writer, comment string) error {
 	if comment == "" {
 		return nil
@ -148,9 +169,10 @@ func (te *tomlEncoder) encodeTopLevelEntry(w io.Writer, path []string, node *Can
 		}
 		if allMaps {
 			key := path[len(path)-1]
+			quotedKey := tomlKey(key)
 			for _, it := range node.Content {
 				// [[key]] then body
-				if _, err := w.Write([]byte("[[" + key + "]]\n")); err != nil {
+				if _, err := w.Write([]byte("[[" + quotedKey + "]]\n")); err != nil {
 					return err
 				}
 				if err := te.encodeMappingBodyWithPath(w, []string{key}, it); err != nil {
@ -182,7 +204,7 @@ func (te *tomlEncoder) writeAttribute(w io.Writer, key string, value *CandidateN
 	}

 	// Write the attribute
-	line := key + " = " + te.formatScalar(value)
+	line := tomlKey(key) + " = " + te.formatScalar(value)

 	// Add line comment if present
 	if value.LineComment != "" {
@ -207,7 +229,7 @@ func (te *tomlEncoder) writeArrayAttribute(w io.Writer, key string, seq *Candida

 	// Handle empty arrays
 	if len(seq.Content) == 0 {
-		line := key + " = []"
+		line := tomlKey(key) + " = []"
 		if seq.LineComment != "" {
 			lineComment := strings.TrimSpace(seq.LineComment)
 			if !strings.HasPrefix(lineComment, "#") {
@ -230,7 +252,7 @@ func (te *tomlEncoder) writeArrayAttribute(w io.Writer, key string, seq *Candida

 	if hasElementComments {
 		// Write multiline array format with comments
-		if _, err := w.Write([]byte(key + " = [\n")); err != nil {
+		if _, err := w.Write([]byte(tomlKey(key) + " = [\n")); err != nil {
 			return err
 		}

@ -321,7 +343,7 @@ func (te *tomlEncoder) writeArrayAttribute(w io.Writer, key string, seq *Candida
 		}
 	}

-	line := key + " = [" + strings.Join(items, ", ") + "]"
+	line := tomlKey(key) + " = [" + strings.Join(items, ", ") + "]"

 	// Add line comment if present
 	if seq.LineComment != "" {
@ -369,21 +391,21 @@ func (te *tomlEncoder) mappingToInlineTable(m *CandidateNode) (string, error) {
 		v := m.Content[i+1]
 		switch v.Kind {
 		case ScalarNode:
-			parts = append(parts, fmt.Sprintf("%s = %s", k, te.formatScalar(v)))
+			parts = append(parts, fmt.Sprintf("%s = %s", tomlKey(k), te.formatScalar(v)))
 		case SequenceNode:
 			// inline array in inline table
 			arr, err := te.sequenceToInlineArray(v)
 			if err != nil {
 				return "", err
 			}
-			parts = append(parts, fmt.Sprintf("%s = %s", k, arr))
+			parts = append(parts, fmt.Sprintf("%s = %s", tomlKey(k), arr))
 		case MappingNode:
 			// nested inline table
 			inline, err := te.mappingToInlineTable(v)
 			if err != nil {
 				return "", err
 			}
-			parts = append(parts, fmt.Sprintf("%s = %s", k, inline))
+			parts = append(parts, fmt.Sprintf("%s = %s", tomlKey(k), inline))
 		default:
 			return "", fmt.Errorf("unsupported inline table value kind: %v", v.Kind)
 		}
@ -396,7 +418,7 @@ func (te *tomlEncoder) writeInlineTableAttribute(w io.Writer, key string, m *Can
 	if err != nil {
 		return err
 	}
-	_, err = w.Write([]byte(key + " = " + inline + "\n"))
+	_, err = w.Write([]byte(tomlKey(key) + " = " + inline + "\n"))
 	return err
 }

@ -418,7 +440,7 @@ func (te *tomlEncoder) writeTableHeader(w io.Writer, path []string, m *Candidate
 	}

 	// Write table header [a.b.c]
-	header := "[" + strings.Join(path, ".") + "]\n"
+	header := "[" + tomlDottedKey(path) + "]\n"
 	_, err := w.Write([]byte(header))
 	return err
 }
@ -486,7 +508,7 @@ func (te *tomlEncoder) encodeSeparateMapping(w io.Writer, path []string, m *Cand
 				}
 			}
 			if allMaps {
-				key := strings.Join(append(append([]string{}, path...), k), ".")
+				key := tomlDottedKey(append(append([]string{}, path...), k))
 				for _, it := range v.Content {
 					if _, err := w.Write([]byte("[[" + key + "]]\n")); err != nil {
 						return err
@ -574,7 +596,7 @@ func (te *tomlEncoder) encodeMappingBodyWithPath(w io.Writer, path []string, m *
 				}
 			}
 			if allMaps {
-				dotted := strings.Join(append(append([]string{}, path...), k), ".")
+				dotted := tomlDottedKey(append(append([]string{}, path...), k))
 				for _, it := range v.Content {
 					if _, err := w.Write([]byte("[[" + dotted + "]]\n")); err != nil {
 						return err
--- a/pkg/yqlib/lexer_participle.go
+++ b/pkg/yqlib/lexer_participle.go
@ -96,6 +96,8 @@ var participleYqRules = []*participleYqRule{
 	simpleOp("load_?str|str_?load", loadStringOpType),
 	{"LoadYaml", `load`, loadOp(NewYamlDecoder(LoadYamlPreferences)), 0},

+	simpleOp("system", systemOpType),
+
 	{"SplitDocument", `splitDoc|split_?doc`, opToken(splitDocumentOpType), 0},

 	simpleOp("select", selectOpType),
--- a/pkg/yqlib/lib_test.go
+++ b/pkg/yqlib/lib_test.go
@ -24,7 +24,7 @@ type parseSnippetScenario struct {
 var parseSnippetScenarios = []parseSnippetScenario{
 	{
 		snippet:       ":",
-		expectedError: "yaml: did not find expected key",
+		expectedError: "yaml: while parsing a block mapping at <unknown position>: did not find expected key",
 	},
 	{
 		snippet: "",
--- a/pkg/yqlib/operation.go
+++ b/pkg/yqlib/operation.go
@ -164,6 +164,8 @@ var stringInterpolationOpType = &operationType{Type: "STRING_INT", NumArgs: 0, P
 var loadOpType = &operationType{Type: "LOAD", NumArgs: 1, Precedence: 52, Handler: loadOperator, CheckForPostTraverse: true}
 var loadStringOpType = &operationType{Type: "LOAD_STRING", NumArgs: 1, Precedence: 52, Handler: loadStringOperator}

+var systemOpType = &operationType{Type: "SYSTEM", NumArgs: 1, Precedence: 50, Handler: systemOperator}
+
 var keysOpType = &operationType{Type: "KEYS", NumArgs: 0, Precedence: 52, Handler: keysOperator, CheckForPostTraverse: true}

 var collectObjectOpType = &operationType{Type: "COLLECT_OBJECT", NumArgs: 0, Precedence: 50, Handler: collectObjectOperator}
--- a/pkg/yqlib/operator_multiply_test.go
+++ b/pkg/yqlib/operator_multiply_test.go
@ -553,7 +553,7 @@ var multiplyOperatorScenarios = []expressionScenario{
 		document:   document,
 		expression: `.b * .c`,
 		expected: []string{
-			"D0, P[b], (!!map)::{name: dog, <<: *cat}\n",
+			"D0, P[b], (!!map)::{name: dog, \"<<\": *cat}\n",
 		},
 	},
 	{
--- a/pkg/yqlib/operator_system.go
+++ b/pkg/yqlib/operator_system.go
@ -0,0 +1,146 @@
+package yqlib
+
+import (
+	"bytes"
+	"container/list"
+	"fmt"
+	"os/exec"
+	"strings"
+)
+
+func resolveSystemArgs(argsNode *CandidateNode) ([]string, error) {
+	if argsNode == nil {
+		return nil, nil
+	}
+
+	if argsNode.Kind == SequenceNode {
+		args := make([]string, 0, len(argsNode.Content))
+		for _, child := range argsNode.Content {
+			// Only non-null scalar children are valid arguments.
+			if child == nil {
+				continue
+			}
+			if child.Kind != ScalarNode || child.Tag == "!!null" {
+				return nil, fmt.Errorf("system operator: argument must be a non-null scalar; got kind=%v tag=%v", child.Kind, child.Tag)
+			}
+			args = append(args, child.Value)
+		}
+		if len(args) == 0 {
+			return nil, nil
+		}
+		return args, nil
+	}
+
+	// Single-argument case: only accept a non-null scalar node.
+	if argsNode.Tag == "!!null" {
+		return nil, nil
+	}
+	if argsNode.Kind != ScalarNode {
+		return nil, fmt.Errorf("system operator: args must be a non-null scalar or sequence of non-null scalars; got kind=%v tag=%v", argsNode.Kind, argsNode.Tag)
+	}
+	return []string{argsNode.Value}, nil
+}
+
+func resolveCommandNode(commandNodes Context) (string, error) {
+	if commandNodes.MatchingNodes.Front() == nil {
+		return "", fmt.Errorf("system operator: command expression returned no results")
+	}
+	if commandNodes.MatchingNodes.Len() > 1 {
+		log.Debugf("system operator: command expression returned %d results, using first", commandNodes.MatchingNodes.Len())
+	}
+	cmdNode := commandNodes.MatchingNodes.Front().Value.(*CandidateNode)
+	if cmdNode.Kind != ScalarNode || cmdNode.guessTagFromCustomType() != "!!str" {
+		return "", fmt.Errorf("system operator: command must be a string scalar")
+	}
+	if cmdNode.Value == "" {
+		return "", fmt.Errorf("system operator: command must be a non-empty string")
+	}
+	return cmdNode.Value, nil
+}
+
+func systemOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
+	if !ConfiguredSecurityPreferences.EnableSystemOps {
+		return Context{}, fmt.Errorf("system operations are disabled, use --security-enable-system-operator to enable")
+	}
+
+	// determine at parse time whether we have (command; args) or just (command)
+	hasArgs := expressionNode.RHS.Operation.OperationType == blockOpType
+
+	var results = list.New()
+
+	for el := context.MatchingNodes.Front(); el != nil; el = el.Next() {
+		candidate := el.Value.(*CandidateNode)
+		nodeContext := context.SingleReadonlyChildContext(candidate)
+
+		var command string
+		var args []string
+
+		if hasArgs {
+			block := expressionNode.RHS
+			commandNodes, err := d.GetMatchingNodes(nodeContext, block.LHS)
+			if err != nil {
+				return Context{}, err
+			}
+			command, err = resolveCommandNode(commandNodes)
+			if err != nil {
+				return Context{}, err
+			}
+
+			argsNodes, err := d.GetMatchingNodes(nodeContext, block.RHS)
+			if err != nil {
+				return Context{}, err
+			}
+			if argsNodes.MatchingNodes.Len() > 1 {
+				log.Debugf("system operator: args expression returned %d results, using first", argsNodes.MatchingNodes.Len())
+			}
+			if argsNodes.MatchingNodes.Front() != nil {
+				args, err = resolveSystemArgs(argsNodes.MatchingNodes.Front().Value.(*CandidateNode))
+				if err != nil {
+					return Context{}, err
+				}
+			}
+		} else {
+			commandNodes, err := d.GetMatchingNodes(nodeContext, expressionNode.RHS)
+			if err != nil {
+				return Context{}, err
+			}
+			command, err = resolveCommandNode(commandNodes)
+			if err != nil {
+				return Context{}, err
+			}
+		}
+
+		var stdin bytes.Buffer
+		encoded, err := encodeToYamlString(candidate)
+		if err != nil {
+			return Context{}, err
+		}
+		stdin.WriteString(encoded)
+
+		// #nosec G204 - intentional: user must explicitly enable this operator
+		cmd := exec.Command(command, args...)
+		cmd.Stdin = &stdin
+		var stderr bytes.Buffer
+		cmd.Stderr = &stderr
+
+		output, err := cmd.Output()
+		if err != nil {
+			stderrStr := strings.TrimSpace(stderr.String())
+			if stderrStr != "" {
+				return Context{}, fmt.Errorf("system command '%v' failed: %w\nstderr: %v", command, err, stderrStr)
+			}
+			return Context{}, fmt.Errorf("system command '%v' failed: %w", command, err)
+		}
+
+		result := string(output)
+		if strings.HasSuffix(result, "\r\n") {
+			result = result[:len(result)-2]
+		} else if strings.HasSuffix(result, "\n") {
+			result = result[:len(result)-1]
+		}
+		newNode := candidate.CreateReplacement(ScalarNode, "!!str", result)
+		results.PushBack(newNode)
+	}
+
+	return context.ChildContext(results), nil
+}
--- a/pkg/yqlib/operator_system_test.go
+++ b/pkg/yqlib/operator_system_test.go
@ -0,0 +1,123 @@
+package yqlib
+
+import (
+	"os/exec"
+	"testing"
+)
+
+func findExec(t *testing.T, name string) string {
+	t.Helper()
+	path, err := exec.LookPath(name)
+	if err != nil {
+		t.Skipf("skipping: %v not found: %v", name, err)
+	}
+	return path
+}
+
+var systemOperatorDisabledScenarios = []expressionScenario{
+	{
+		description:    "system operator returns error when disabled",
+		subdescription: "Use `--security-enable-system-operator` to enable the system operator.",
+		document:       "country: Australia",
+		expression:     `.country = system("/usr/bin/echo"; "test")`,
+		expectedError:  "system operations are disabled, use --security-enable-system-operator to enable",
+	},
+}
+
+func TestSystemOperatorDisabledScenarios(t *testing.T) {
+	originalEnableSystemOps := ConfiguredSecurityPreferences.EnableSystemOps
+	defer func() {
+		ConfiguredSecurityPreferences.EnableSystemOps = originalEnableSystemOps
+	}()
+
+	ConfiguredSecurityPreferences.EnableSystemOps = false
+
+	for _, tt := range systemOperatorDisabledScenarios {
+		testScenario(t, &tt)
+	}
+	documentOperatorScenarios(t, "system-operators", systemOperatorDisabledScenarios)
+}
+
+func TestSystemOperatorEnabledScenarios(t *testing.T) {
+	echoPath := findExec(t, "echo")
+	falsePath := findExec(t, "false")
+
+	originalEnableSystemOps := ConfiguredSecurityPreferences.EnableSystemOps
+	defer func() {
+		ConfiguredSecurityPreferences.EnableSystemOps = originalEnableSystemOps
+	}()
+
+	ConfiguredSecurityPreferences.EnableSystemOps = true
+
+	scenarios := []expressionScenario{
+		{
+			description:    "Run a command with an argument",
+			subdescription: "Use `--security-enable-system-operator` to enable the system operator.",
+			yqFlags:        "--security-enable-system-operator",
+			document:       "country: Australia",
+			expression:     `.country = system("` + echoPath + `"; "test")`,
+			expected: []string{
+				"D0, P[], (!!map)::country: test\n",
+			},
+		},
+		{
+			description:    "Run a command without arguments",
+			subdescription: "Omit the semicolon and args to run the command with no extra arguments.",
+			yqFlags:        "--security-enable-system-operator",
+			document:       "a: hello",
+			expression:     `.a = system("` + echoPath + `")`,
+			expected: []string{
+				"D0, P[], (!!map)::a: \"\"\n",
+			},
+		},
+		{
+			description:    "Run a command with multiple arguments",
+			subdescription: "Pass an array of arguments.",
+			skipDoc:        true,
+			document:       "a: hello",
+			expression:     `.a = system("` + echoPath + `"; ["foo", "bar"])`,
+			expected: []string{
+				"D0, P[], (!!map)::a: foo bar\n",
+			},
+		},
+		{
+			description: "Command and args are evaluated per matched node",
+			skipDoc:     true,
+			document:    "cmd: " + echoPath + "\narg: hello",
+			expression:  `.result = system(.cmd; .arg)`,
+			expected: []string{
+				"D0, P[], (!!map)::cmd: " + echoPath + "\narg: hello\nresult: hello\n",
+			},
+		},
+		{
+			description:   "Command failure returns error",
+			skipDoc:       true,
+			document:      "a: hello",
+			expression:    `.a = system("` + falsePath + `")`,
+			expectedError: "system command '" + falsePath + "' failed: exit status 1",
+		},
+		{
+			description:   "Null command returns error",
+			skipDoc:       true,
+			document:      "a: hello",
+			expression:    `.a = system(null)`,
+			expectedError: "system operator: command must be a string scalar",
+		},
+		{
+			description: "System operator processes multiple matched nodes",
+			skipDoc:     true,
+			document:    "a: first",
+			document2:   "a: second",
+			expression:  `.a = system("` + echoPath + `"; "replaced")`,
+			expected: []string{
+				"D0, P[], (!!map)::a: replaced\n",
+				"D0, P[], (!!map)::a: replaced\n",
+			},
+		},
+	}
+
+	for _, tt := range scenarios {
+		testScenario(t, &tt)
+	}
+	appendOperatorDocumentScenario(t, "system-operators", scenarios)
+}
--- a/pkg/yqlib/operators_test.go
+++ b/pkg/yqlib/operators_test.go
@ -31,6 +31,7 @@ type expressionScenario struct {
 	dontFormatInputForDoc bool // dont format input doc for documentation generation
 	requiresFormat        string
 	skipForGoccy          bool
+	yqFlags               string // extra yq flags to include in generated doc command snippets
 }

 var goccyTesting = false
@ -356,14 +357,22 @@ func documentInput(w *bufio.Writer, s expressionScenario) (string, string) {

 		writeOrPanic(w, "then\n")

+		flagsPrefix := ""
+		if s.yqFlags != "" {
+			flagsPrefix = s.yqFlags + " "
+		}
 		if s.expression != "" {
-			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v'%v' %v\n```\n", envCommand, command, strings.ReplaceAll(s.expression, "'", `'\''`), files))
+			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v'%v' %v\n```\n", envCommand, flagsPrefix, command, strings.ReplaceAll(s.expression, "'", `'\''`), files))
 		} else {
-			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v\n```\n", envCommand, command, files))
+			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v%v\n```\n", envCommand, flagsPrefix, command, files))
 		}
 	} else {
 		writeOrPanic(w, "Running\n")
-		writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v--null-input '%v'\n```\n", envCommand, command, s.expression))
+		flagsPrefix := ""
+		if s.yqFlags != "" {
+			flagsPrefix = s.yqFlags + " "
+		}
+		writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v--null-input '%v'\n```\n", envCommand, flagsPrefix, command, s.expression))
 	}
 	return formattedDoc, formattedDoc2
 }
--- a/pkg/yqlib/security_prefs.go
+++ b/pkg/yqlib/security_prefs.go
@ -1,11 +1,13 @@
 package yqlib

 type SecurityPreferences struct {
-	DisableEnvOps  bool
-	DisableFileOps bool
+	DisableEnvOps   bool
+	DisableFileOps  bool
+	EnableSystemOps bool
 }

 var ConfiguredSecurityPreferences = SecurityPreferences{
-	DisableEnvOps:  false,
-	DisableFileOps: false,
+	DisableEnvOps:   false,
+	DisableFileOps:  false,
+	EnableSystemOps: false,
 }
--- a/pkg/yqlib/toml_test.go
+++ b/pkg/yqlib/toml_test.go
@ -287,6 +287,18 @@ var expectedSubArrays = `array:
          - {}
 `

+// Keys with special characters that require quoting in TOML
+var rtSpecialKeyInlineTable = `host = { "http://sealos.hub:5000" = { capabilities = ["pull", "resolve", "push"], skip_verify = true } }
+`
+
+var rtSpecialKeyTableSection = `["/tmp/blah"]
+value = "hello"
+`
+
+var rtSpecialKeyDottedTableSection = `[servers."http://localhost:8080"]
+ip = "127.0.0.1"
+`
+
 var tomlScenarios = []formatScenario{
 	{
 		skipDoc:      true,
@ -642,6 +654,30 @@ var tomlScenarios = []formatScenario{
 		expected:     "arg = { hello = \"foo\" }\n",
 		scenarioType: "encode",
 	},
+	{
+		skipDoc:      true,
+		description:  "Roundtrip: key with special characters in inline table",
+		input:        rtSpecialKeyInlineTable,
+		expression:   ".",
+		expected:     rtSpecialKeyInlineTable,
+		scenarioType: "roundtrip",
+	},
+	{
+		skipDoc:      true,
+		description:  "Roundtrip: key with special characters in table section",
+		input:        rtSpecialKeyTableSection,
+		expression:   ".",
+		expected:     rtSpecialKeyTableSection,
+		scenarioType: "roundtrip",
+	},
+	{
+		skipDoc:      true,
+		description:  "Roundtrip: special character key in dotted table section header",
+		input:        rtSpecialKeyDottedTableSection,
+		expression:   ".",
+		expected:     rtSpecialKeyDottedTableSection,
+		scenarioType: "roundtrip",
+	},
 }

 func testTomlScenario(t *testing.T, s formatScenario) {