Added documentation for the node tool shell

[AditM99]

Summary

Added documentation for the node tool shell

Type

Documentation

Testing

No testing only documentation update

Checklist

• Commit messages follow conventional commits
• No secrets or credentials included
• Wiki updated (if applicable)
• Breaking changes documented (if applicable)

Linked Issue

Fixes #653

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for the Shell tool node, including execution function parameters, exit code meanings, configuration options, host execution security notes, command allowlist behavior, and recommendations for git-related workflows.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation is added for the Shell tool node, describing its purpose of executing host shell commands, the shell.execute function interface with its parameters, exit code semantics, configuration options including timeouts and allowlists, and operational notes about privilege elevation and validation behavior.

Changes

Shell Tool Documentation

Layer / File(s)	Summary
Documentation Structure nodes/src/nodes/tool_shell/README.md	Frontmatter and page introduction establish the Shell tool documentation page.
Tool Interface & Semantics nodes/src/nodes/tool_shell/README.md	The shell.execute function is defined with parameters (command, working_dir, env, timeout) and exit code meanings (-1 for timeout kill, 127 for shell launch failure).
Configuration & Operational Details nodes/src/nodes/tool_shell/README.md	Configuration fields document default working directory, execution timeout behavior, output size limits, environment variable handling, command allowlist matching using re.fullmatch, host privilege model (no sandbox), and validation behavior. Guidance recommends the Git node for portable git workflows.

Estimated Code Review Effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A shell tool document now takes flight,
Commands execute with full host might,
Timeouts, allowlists, env vars too,
Parameters and configs perfectly new! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Added documentation for the node tool shell' directly and clearly summarizes the main change—adding documentation for the Shell tool node.
Linked Issues check	✅ Passed	The documentation covers all acceptance criteria: command execution, stdout/stderr returns, working directory configuration, and environment variable injection per execution.
Out of Scope Changes check	✅ Passed	The pull request only adds documentation for the Shell tool node as required by issue #653; no out-of-scope code changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

No description provided.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@nodes/src/nodes/tool_shell/README.md`:
- Around line 23-44: The README's shell.execute section needs a concrete
request/response example and allowlist patterns to show safe usage: add a
minimal JSON request payload (fields: command, working_dir, env, timeout) and
the example response shape (stdout, stderr, exit_code) under the "shell.execute
parameters" section, and add sample allowlist regexes (e.g.
^npm\\s+(ci|test)(\\s+.*)?$, ^python\\s+scripts/[-\\w./]+$ and a note about
using .* for substring matches) to the "Command allowlist" description so
readers can copy/paste a working example; update references to shell.execute and
the Command allowlist text accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 87da70dd-9161-4d36-8a54-d8c60c9e30e7

📥 Commits

Reviewing files that changed from the base of the PR and between 5d9963f and 768bfdb.

📒 Files selected for processing (1)

• nodes/src/nodes/tool_shell/README.md

[coderabbitai]

🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Add one concrete request/response + allowlist example.

A minimal example for shell.execute payload and allowlist patterns would make this safer and faster to adopt.

✍️ Suggested doc addition

 ## As a tool
@@
 `exit_code` is the process return code. `-1` indicates a timeout kill; `127` indicates the host shell could not be launched.
+
+**Example call:**
+
+```json
+{
+  "command": "npm ci && npm test",
+  "working_dir": "/workspace/app",
+  "env": { "NODE_ENV": "test" },
+  "timeout": 120
+}
+```
+
+**Example response shape:**
+
+```json
+{
+  "stdout": "...",
+  "stderr": "",
+  "exit_code": 0
+}
+```
@@
 | Command allowlist             | —         | Regex patterns. If non-empty, the full command must match at least one (`re.fullmatch`). Use `.*` for substring matches    |
+
+Examples:
+- `^npm\\s+(ci|test)(\\s+.*)?$` allows npm ci/test commands
+- `^python\\s+scripts/[-\\w./]+$` allows script execution under `scripts/`

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@nodes/src/nodes/tool_shell/README.md` around lines 23 - 44, The README's
shell.execute section needs a concrete request/response example and allowlist
patterns to show safe usage: add a minimal JSON request payload (fields:
command, working_dir, env, timeout) and the example response shape (stdout,
stderr, exit_code) under the "shell.execute parameters" section, and add sample
allowlist regexes (e.g. ^npm\\s+(ci|test)(\\s+.*)?$,
^python\\s+scripts/[-\\w./]+$ and a note about using .* for substring matches)
to the "Command allowlist" description so readers can copy/paste a working
example; update references to shell.execute and the Command allowlist text
accordingly.

[asclearuc]

Thank you.
Make it a part of #739
Closing it.