146 lines
3.7 KiB
Markdown
146 lines
3.7 KiB
Markdown
# SCP Plugin Walkthrough
|
|
|
|
This walkthrough adds a bundled `scp` plugin backed by existing SSH libraries:
|
|
|
|
- `paramiko` for SSH and SFTP directory listing
|
|
- `scp` for file transfers
|
|
|
|
The implementation lives in [plugins/scp/__init__.py](plugins/scp/__init__.py).
|
|
|
|
## What The Plugin Does
|
|
|
|
The SCP plugin mirrors the FTP walkthrough, but on top of SSH:
|
|
|
|
- `search-file -plugin scp -instance <name> ...` lists remote files and folders over SFTP.
|
|
- plain `@N` on a folder drills into that directory.
|
|
- plain `@N` on a file runs `download-file -plugin scp -instance <name> -url ...`.
|
|
- `@N | add-file -instance ...` downloads first, then ingests the local temp file.
|
|
- `add-file -plugin scp -instance <name> -path ...` uploads a local file to the configured remote path.
|
|
|
|
## Example Config
|
|
|
|
```toml
|
|
[provider.scp.work]
|
|
host = "ssh.example.com"
|
|
port = 22
|
|
username = "deploy"
|
|
password = "secret"
|
|
key_path = "C:/Users/Admin/.ssh/id_ed25519"
|
|
base_path = "/srv/files"
|
|
timeout = 20
|
|
search_depth = 1
|
|
allow_agent = true
|
|
look_for_keys = true
|
|
|
|
[provider.scp.archive]
|
|
host = "ssh-archive.example.com"
|
|
port = 2222
|
|
username = "archive"
|
|
key_path = "C:/Users/Admin/.ssh/archive_ed25519"
|
|
base_path = "/srv/archive"
|
|
timeout = 20
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `work` and `archive` are instance names; use them with `-instance work` or `-instance archive`.
|
|
- `host` and `username` are required for each instance to validate.
|
|
- You can use password auth, key auth, or both.
|
|
- `base_path` is both the default search root and the default upload directory.
|
|
|
|
## Search Flow
|
|
|
|
List the configured base path:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "*"
|
|
```
|
|
|
|
Search by filename:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "invoice"
|
|
```
|
|
|
|
Search another subtree with deeper recursion:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "path:/srv/files/releases depth:2 *.zip"
|
|
```
|
|
|
|
Show only folders:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "path:/srv/files type:folder *"
|
|
```
|
|
|
|
## Selection Flow
|
|
|
|
Folder rows are navigation rows:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "*"
|
|
@2
|
|
```
|
|
|
|
File rows carry an explicit row action, so terminal selection downloads directly:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "report"
|
|
@1
|
|
```
|
|
|
|
That expands to the equivalent of:
|
|
|
|
```powershell
|
|
download-file -plugin scp -instance work -url scp://ssh.example.com/srv/files/report.pdf
|
|
```
|
|
|
|
## Download And Add-File Flow
|
|
|
|
Download into a local folder:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "report"
|
|
@1 | download-file -path C:\Downloads
|
|
```
|
|
|
|
Ingest a selected remote file into a configured instance backend:
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "report"
|
|
@1 | add-file -instance tutorial
|
|
```
|
|
|
|
Why this works:
|
|
|
|
- file rows advertise `_selection_action` for `download-file`
|
|
- `add-file` selection replay inserts that provider download stage before ingest
|
|
- the plugin also implements `resolve_pipe_result_download()` for provider-owned SCP rows
|
|
- file rows also carry the chosen `instance`, so replay stays bound to the same SSH target
|
|
|
|
## Upload Flow
|
|
|
|
Upload a local file to the configured remote `base_path`:
|
|
|
|
```powershell
|
|
add-file -plugin scp -instance archive -path C:\Media\report.pdf
|
|
```
|
|
|
|
## Implementation Notes
|
|
|
|
The plugin uses SFTP for directory listing because SCP itself is a transfer protocol, not a browse/search protocol. That split keeps the provider simple:
|
|
|
|
- browse and metadata via Paramiko SFTP
|
|
- file transfer via the `scp` package
|
|
|
|
## Recommended Demo Commands
|
|
|
|
```powershell
|
|
search-file -plugin scp -instance work "*"
|
|
search-file -plugin scp -instance work "path:/srv/files depth:2 *.zip"
|
|
@1
|
|
@1 | download-file -path C:\Downloads
|
|
@1 | add-file -instance tutorial
|
|
add-file -plugin scp -instance archive -path C:\Media\report.pdf
|
|
``` |