Better parameter documentation for `execute_run` -> `command`

Metadata

Project: craft-providers
Number: #116
Type: issue
State: open
Author: jugmac00
Labels: Type: Documentation
Created: 2022-04-28 05:54 AM UTC
Updated: 2026-04-22 02:50 AM UTC
Closed: —

Current evaluation

execute_run still documents command only as “Command to execute”; users need explicit argument-list, escaping, and shell-feature guidance, leaving this triaged documentation request unresolved.

Suggested action: keep open

Reason: The issue has a Type: Documentation label and a maintainer analysis explaining that argument-vector execution intentionally prevents redirects and pipes, but the current executor and provider docstrings still say only “Command to execute.” Documentation should explain that command is an argument list, elements are passed literally without shell interpretation, and shell syntax requires an explicit shell invocation.

Evaluated by: mr-cal-bot

Impact: 32 Quick Win: 21 Complexity: 24 Confidence: 95 Actionability: 88

Issue body

The current docstring/param documentation looks like.. ``` :param command: Command to execute. ``` When you have a look at the type annotations, it is clear that `command` is a list of "command parts". Unfortunately there is no description on how this list should look like I had some issues creating a correct list for a `sed` command. This was my attempt... ``` update_sources_list = [ "sed", "-i", f"'1s=^={lines}='", "/etc/apt/sources.list" ] ``` ... and that even works when I join it and execute it, but it did not work when passing into `execute_run` as then some additional escaping happens, and the then assembled `sed` command was broken. I'd appreciate an improved parameter documentation which clearly describes how the list should look like, especially when you need to escape things. The solution to the above problem was to remove the single ticks, as after the list was passed into `execute_run` the list entry was escaped there.

Evaluation history

Date	Model	Scores	Action	Summary
2026-10-02 08:16 PM UTC	stealth/space-bunny-alpha	Impact: 32 Quick Win: 21 Complexity: 24 Confidence: 95 Actionability: 88	keep open	execute_run still documents command only as “Command to execute”; users need explicit argument-list, escaping, and shell-feature guidance, leaving this triaged documentation request unresolved.
2026-09-24 09:10 PM UTC	stealth/space-bunny-alpha	Impact: 35 Quick Win: 21 Complexity: 28 Confidence: 94 Actionability: 82	keep open	Clarify execute_run command argument vectors and shell escaping; acknowledged by a maintainer, but the repeated generic parameter documentation remains unresolved.
2026-09-05 04:31 AM UTC	qwen3.6-35b-a3b-mtp-q6	Impact: 40 Quick Win: 36 Staleness: 60 Complexity: 10 Confidence: 75 Support Request: 20	keep open	Documentation request to clarify `command` parameter escaping in `execute_run`. Maintainer explained `shlex.join()` prevents shell metacharacters for security. Open for ~4 years.
2026-07-22 02:47 PM UTC	qwen/qwen3.6-35b-a3b	Staleness: 70 Complexity: 20 Confidence: 85 Support Request: 30	keep open	Request for improved documentation on the command parameter list format and escaping rules. Maintainer explained shlex.join prevents shell injection in lxc exec, but no API change or doc update has been made.
2026-07-10 01:22 PM UTC	qwen3.6-35b-a3b-mtp-q6	Staleness: 55 Complexity: 20 Confidence: 85 Support Request: 40	keep open	Documentation request to clarify execute_run command parameter list format and escaping. Maintainer explained shlex.join prevents shell injection, but the API remains unintuitive for shell features.

Update history

No update history recorded yet.

Related work

Related To: craft-parts#211 (confidence 99%)
The identically titled cross-project issue was closed as misreported because execute_run documentation belongs in craft-providers.

Related issues

Issue	Project	State	Summary	Similarity
#211 Please improve parameter documentation for `execute_run` -> `command`	craft-parts	closed	Documentation request for `execute_run`'s `command` param was closed as out of scope for craft-parts; maintainer jugmac00 (2022-04-28) redirected it to craft-providers, where canonical/craft-providers#116 remains open and unimplemented.	80%