Check whether the SSH connection to the remote host is alive.

Returns connection status and diagnostics. If it can't connect, the message explains what to check (host reachability, key / agent / ~/.ssh/config setup).

Args: host: SSH host alias from config. Uses default if omitted.

Execute a shell command on the remote server.

The command runs in a bash login shell with the configured environment preamble (e.g., sourced setup scripts) already applied.

Args: command: Shell command to run (e.g., "make test", "python script.py"). cwd: Working directory on the remote. Defaults to the host's configured default_cwd. timeout: Timeout in seconds. Defaults to host config (usually 30s). host: SSH host alias from config. Uses default if omitted.

Start a long-running command in the background on the remote server.

Use this for commands that take more than 30 seconds (e.g., builds, test suites). The command runs detached via nohup. Use ssh_job_status to check progress and retrieve output.

Args: command: Shell command to run in the background. cwd: Working directory on the remote. Defaults to host's default_cwd. job_id: Optional human-readable job ID. Auto-generated if omitted. host: SSH host alias from config. Uses default if omitted.

Check the status of a background job and retrieve its output.

Args: job_id: The job ID returned by ssh_run_background. tail_lines: Number of lines to show from the end of stdout/stderr. host: SSH host alias from config. Uses default if omitted.

Read lines from a file on the remote server.

Efficiently reads only the requested range using sed, so large files are safe to read partially. Returns line-numbered content similar to cat -n output.

Args: path: Absolute or relative path to the file on the remote. offset: Line number to start reading from (0-based). limit: Maximum number of lines to return. host: SSH host alias from config. Uses default if omitted.

Write content to a file on the remote server.

Uses atomic write (temp file + mv) to prevent partial writes. Overwrites the file if it exists, creates it if it doesn't.

Args: path: Absolute or relative path on the remote. content: Text content to write. create_dirs: If true, create parent directories if they don't exist. host: SSH host alias from config. Uses default if omitted.

List directory contents on the remote server.

Args: path: Directory path to list. Defaults to current working directory. pattern: Glob pattern to filter entries (e.g., "*.py", "Makefile"). recursive: If true, list recursively. max_entries: Maximum entries to return (prevents overwhelming output). host: SSH host alias from config. Uses default if omitted.

Get detailed information about a file or directory on the remote server.

Args: path: Path to inspect. host: SSH host alias from config. Uses default if omitted.

Replace a string in a file on the remote server.

Reads the file, performs the replacement locally, and writes it back. The old string must appear exactly once (to avoid ambiguous edits).

Args: path: Path to the file on the remote. old: The exact text to find and replace. Must be unique in the file. new: The replacement text. host: SSH host alias from config. Uses default if omitted.

Create a directory on the remote server.

Args: path: Directory path to create. parents: If true, create parent directories as needed (mkdir -p). host: SSH host alias from config. Uses default if omitted.

Move or rename a file/directory on the remote server.

Args: source: Current path. dest: New path. host: SSH host alias from config. Uses default if omitted.

Delete a file or directory on the remote server.

Args: path: Path to delete. recursive: If true, delete directories recursively (rm -r). host: SSH host alias from config. Uses default if omitted.

Download a file from the remote server to the local machine (binary-safe).

Transfers over SFTP (the SSH file-transfer protocol), so it streams and preserves any file type exactly, including binary (.db, images, archives). To send a file the other way, use ssh_upload.

Args: remote_path: Path to the file on the remote server. local_dir: Local directory to save to. Defaults to ~/Downloads. host: SSH host alias from config. Uses default if omitted.

Upload a local file to the remote server (binary-safe, via SFTP/scp).

Use this for any file type — including binary files such as SQLite .db databases, images, or archives — that ssh_write_file (text/UTF-8) cannot carry safely. The file is streamed over SFTP, so large files transfer without loading into memory.

Args: local_path: Path to the file on THIS machine (the one running the server). remote_path: Destination path on the remote server. create_dirs: If true, create the remote parent directory first. host: SSH host alias from config. Uses default if omitted.

Append text to the end of a file on the remote server.

Efficient for adding content to large files — no read round-trip needed. The file is created if it does not exist.

Args: path: Path to the file on the remote. content: Text content to append. host: SSH host alias from config. Uses default if omitted.

Insert text after a specific line number in a file on the remote server.

Operates directly via sed on the remote — no full-file transfer needed. Only the new content is sent over the wire.

Args: path: Path to the file on the remote. after_line: Line number to insert after (1-based). Use 0 to insert at the beginning. content: Text content to insert. host: SSH host alias from config. Uses default if omitted.

Replace a range of lines in a file on the remote server.

Operates directly via sed on the remote — no full-file transfer needed. If content is empty, the lines are deleted. Both start_line and end_line are 1-based and inclusive.

Args: path: Path to the file on the remote. start_line: First line to replace (1-based, inclusive). end_line: Last line to replace (1-based, inclusive). content: Replacement text. Empty string deletes the line range. host: SSH host alias from config. Uses default if omitted.

Search for a pattern in files on the remote server using grep.

Returns matching lines with file paths and line numbers.

Args: pattern: Regular expression pattern to search for. path: Directory or file to search in. glob: Filter files by glob pattern (e.g., ".py", ".cpp"). max_results: Maximum number of matching lines to return. context_lines: Number of context lines to show before and after each match. case_insensitive: If true, ignore case when matching. host: SSH host alias from config. Uses default if omitted.

Find files by name pattern on the remote server.

Args: path: Directory to search in. pattern: Filename glob pattern (e.g., ".py", "test_"). file_type: Type filter: "f" for files, "d" for directories, "" for both. max_results: Maximum entries to return. max_depth: Maximum directory depth to search. host: SSH host alias from config. Uses default if omitted.

Get git status of a repository on the remote server.

Returns the current branch, modified files, staged files, and untracked files.

Args: cwd: Path to the git repository. Defaults to host's default_cwd. host: SSH host alias from config. Uses default if omitted.

Show git diff on the remote server.

Args: cwd: Path to the git repository. Defaults to host's default_cwd. ref: Git ref to diff against (e.g., "HEAD~1", "main", a commit hash). Empty for working tree diff. path: Limit diff to a specific file or directory. staged: If true, show staged changes (--cached). host: SSH host alias from config. Uses default if omitted.

Show git log on the remote server.

Args: cwd: Path to the git repository. Defaults to host's default_cwd. count: Number of commits to show. path: Limit log to a specific file or directory. oneline: If true, show compact one-line format. host: SSH host alias from config. Uses default if omitted.