ssh_file_find_lines_with_pattern
Search a remote file for a text or regex pattern and return matching lines with line numbers. Use it to find exact lines before editing or viewing surrounding context.
Instructions
Search for a pattern in a remote file and return matching lines with their line numbers. Use this to find WHERE a pattern occurs before using ssh_file_get_context_around_line to see surrounding lines, or ssh_file_replace_line/ssh_file_delete_line_by_content to edit (those require an exact, unique line match - this tool helps you find that exact line first).
Regex flavor differs by platform when regex=True: POSIX extended regex
(grep -E) on Linux/macOS - avoid PCRE-only syntax like \d, use [0-9] or
[[:digit:]] instead; Python's re module on Windows (matched locally after
an SFTP read, not via PowerShell - see below). When regex=False (default),
the pattern is matched as a literal fixed string on every platform.
On Windows, this reads the whole file via SFTP and matches locally in Python, rather than shelling out to PowerShell/Select-String - matched line content could otherwise come back corrupted for non-ASCII text, since Windows' console encodes stdout in its OEM code page rather than UTF-8 (the same problem ssh_file_read's SFTP approach avoids).
Returns:
{'total_matches': int, 'matches': [{'line_number': int, 'content': str}, ...]}.
No matches is not an error - total_matches is 0 and matches is []. On
failure (e.g. file not found, permission denied), an 'error' key is present
instead.
Long-running calls: if this takes longer than the server's wait cap (default 50s), it
returns {"status": "in_progress", "handle_id": ...} instead of the result - the work keeps
running. Get the result by polling ssh_cmd_check_status(handle_id=...), which returns this
tool's normal response once finished. Do not call it again meanwhile. Only one such
operation runs at a time; another one started meanwhile fails with a 'busy' error.Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| regex | No | Whether to treat pattern as a regular expression | |
| pattern | Yes | Text or regex pattern to search for | |
| use_sudo | No | Use sudo for the operation | |
| file_path | Yes | Path to the file to search |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||