ssh_file_replace_line_multi
Replace an exact line in a remote file with multiple lines or delete it by passing an empty list, using SSH. Fails if the line is missing or not unique.
Instructions
Replace a line in a file with one or more new lines (or delete it, with an empty list). Use this instead of ssh_file_replace_line when you need to insert more than one line, or delete a line without using the separate ssh_file_delete_line_by_content tool.
match_line must match EXACTLY ONE line in the file (whitespace-trimmed, literal
text - not a pattern); if it matches zero lines or more than one, the operation
fails with a descriptive error rather than guessing. Use
ssh_file_find_lines_with_pattern first if you're not sure the line is unique.
PARAMETERS:
file_path: Path to the file to modify
match_line: Exact line content to match and replace (whitespace-trimmed)
new_lines: List of new lines to insert in place of the match
To replace with multiple lines: use ["first line", "second line", ...]
To delete the line entirely: use [] (empty list)
To replace with an empty line: use [""]
use_sudo: Use sudo for the operation (default: false)
force: No longer needed (kept for compatibility) - use_sudo reads root-only files with sudo (default: false)
RETURNS:
On success: {'success': True, 'lines_written': <len(new_lines)>} (or, in the
rare edge case where the result is byte-identical to the original file,
{'success': True, 'message': 'No changes needed...'} instead). On failure
(match not found, match not unique, file not found/unreadable): {'success': False, 'error': str} - not a raised exception. Note: does NOT return file_path
in the response.
EXAMPLES: Example 1: Replace a line with multiple lines
{
"file_path": "/etc/hosts",
"match_line": "127.0.0.1 localhost",
"new_lines": ["127.0.0.1 localhost", "127.0.0.1 myhost.local"]
}Example 2: Delete a line entirely
{
"file_path": "/etc/nginx/nginx.conf",
"match_line": "# server_tokens off;",
"new_lines": []
}Example 3: Replace with an empty line
{
"file_path": "/etc/ssh/sshd_config",
"match_line": "PermitRootLogin yes",
"new_lines": [""]
}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 |
|---|---|---|---|
| force | No | No longer needed (kept for compatibility): with use_sudo=true the file is read with sudo when the user can't read it. If it can't be read at all, the edit fails - it never reports success without having seen the file. | |
| use_sudo | No | Use sudo for the operation | |
| file_path | Yes | Path to the file to modify | |
| new_lines | Yes | List of new lines to insert in place of the match | |
| match_line | Yes | Exact line content to match and replace |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||