ssh_file_replace_line
Replace an exact line in a remote file via SSH, requiring a unique match. Fails with an error if the match is missing or ambiguous, preventing unintended edits.
Instructions
Replace a line in a file with a new line. 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 which line you meant. 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_line: New line to insert in place of the match
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': 1} (or, in the rare edge case
where new_line is identical to the matched line, {'success': True, 'message': 'No changes needed...'} instead - nothing to write). On failure (match not
found, match not unique, file not found/unreadable): {'success': False, 'error': str} - not a raised exception. Note: unlike some other file tools, this does NOT
return file_path in the response.
EXAMPLES: Example 1: Replace a commented line with an active configuration
{
"file_path": "/etc/ssh/sshd_config",
"match_line": "#ClientAliveInterval 0",
"new_line": "ClientAliveInterval 300"
}Note: To delete a line entirely, use the dedicated ssh_file_delete_line_by_content tool instead. To replace/insert MULTIPLE lines in one call, use ssh_file_replace_line_multi 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 |
|---|---|---|---|
| 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. | |
| new_line | Yes | New line to insert in place of the match | |
| use_sudo | No | Use sudo for the operation | |
| file_path | Yes | Path to the file to modify | |
| match_line | Yes | Exact line content to match and replace |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||