mirror of
https://github.com/mikefarah/yq.git
synced 2026-06-29 08:38:48 +00:00
44c55c8a54
* Initial plan * Add system(command; args) operator with --enable-system-operator flag Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/8a11e9a0-10d2-4f2a-ae29-4e9d0bfc266f Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com> * Update pkg/yqlib/operator_system.go Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Evaluate system command/args per matched node using SingleReadonlyChildContext Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/dca841eb-3f63-4f23-adeb-556431560420 Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com> * Add yqFlags to expressionScenario for doc command snippets; fix system op docs Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/3f8a5375-25fd-4428-a8e6-b630194c36b2 Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com> * Update pkg/yqlib/doc/operators/headers/system-operators.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update pkg/yqlib/doc/operators/system-operators.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Validate command node type and handle multiple results with debug log Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/928aabc5-ad71-41d8-94ab-403942e3f92d Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Remove deprecated --enable-system-operator alias; use --security-enable-system-operator consistently Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/286b95e9-b6d7-4ab8-b401-2d7a03853922 Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Address deep review feedback: error on disabled, strict arg/cmd validation, debug logs, docs Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/fbfba2db-60ea-4c20-a4c2-0fd396b80c81 Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com> Co-authored-by: Mike Farah <mikefarah@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
77 lines
2.1 KiB
Markdown
77 lines
2.1 KiB
Markdown
# 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: ""
|
|
```
|
|
|