Medios-Macina/docs/scp_plugin_tutorial.md

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.

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

[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:

search-file -plugin scp -instance work "*"

Search by filename:

search-file -plugin scp -instance work "invoice"

Search another subtree with deeper recursion:

search-file -plugin scp -instance work "path:/srv/files/releases depth:2 *.zip"

Show only folders:

search-file -plugin scp -instance work "path:/srv/files type:folder *"

Selection Flow

Folder rows are navigation rows:

search-file -plugin scp -instance work "*"
@2

File rows carry an explicit row action, so terminal selection downloads directly:

search-file -plugin scp -instance work "report"
@1

That expands to the equivalent of:

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:

search-file -plugin scp -instance work "report"
@1 | download-file -path C:\Downloads

Ingest a selected remote file into a configured instance backend:

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:

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

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