ssh_archive_extract
Extract .tar, .tar.gz, or .zip archives into a directory on a remote SSH host. Format is chosen by file extension and must match the server's OS.
Instructions
Extract an archive to a directory. The accepted format is platform-specific and
determined purely by archive_path's file extension (not by inspecting the
archive's actual content):
Linux/macOS:
.tar.gz,.tgz, or.taronly. A.zipfile (e.g. created by ssh_archive_create on Windows) will fail here with an unsupported-format error.Windows:
.ziponly. A.tar/.tar.gzfile (e.g. created by ssh_archive_create on Linux/macOS) will fail here the same way. There is no cross-platform-portable archive format currently available through this tool - archives must be created and extracted on the same OS family.
overwrite=False (default) does not fail outright if some files already exist at
the destination - on Linux/macOS it extracts everything else and just logs a
warning about the skipped files (no per-file detail returned); on Windows the
behavior follows Expand-Archive's own overwrite handling.
On a 'linux'/'flex' connection with a BusyBox-style tar (check
ssh_conn_connect/ssh_conn_host_info's capabilities), this can raise a
clear error instead of running - unlike the wrong-format/extraction-error
cases below, which return an error dict, this is a raised exception. Two
independent gaps: missing --strip-components blocks extraction entirely
(no clean single-tool fallback - extract without stripping via ssh_cmd_run,
the archive's own top-level directory will remain, then relocate its
contents up one level yourself); missing --keep-old-files only blocks when
overwrite isn't explicitly True - passing overwrite=True avoids that
one specifically.
Returns:
On success: {'status': 'success', 'success': True, 'destination_path', 'files_extracted' (number of files), 'directories' (number of folders), 'extracted_files' (the first 50 file paths, relative to destination_path), 'extracted_files_truncated' (True if there are more), 'note' (how to list them all, and whether existing files were kept because overwrite=False)}. On failure:
{'status': 'error', 'message': str, 'extracted_files': []} - not a raised exception.
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 |
|---|---|---|---|
| use_sudo | No | Use sudo for the operation | |
| overwrite | No | Overwrite existing files | |
| archive_path | Yes | Path to the archive file | |
| destination_path | Yes | Directory to extract to |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||