# SFTP Reference

Use this reference for remote file or directory tasks.

## Default Path

- Treat file and directory tasks as SFTP tasks by default, not shell tasks.
- If the user explicitly says to use only `sftp`, do not call `exec`.
- Every `sftp` command must include both `--session <session-id>` and `--chat-session <chat-session-id>`.
- Do not use reusable SFTP handles or `--sftp <id>`.
- After choosing a target session, first run `session --session <id> --json --chat-session <chat-session-id>` and inspect the returned metadata.
- Use SFTP only when that `session` result shows a connected SSH-backed session. For local, Mosh, Telnet, serial/raw, or network-device sessions, do not use SFTP.
- Keep path semantics strict:
  - `--remote-path` always means a path on the remote host.
  - `--local-path` always means a path on the local machine running Netcatty.
- If the user says "download" to a local destination such as `/tmp`, `~/Downloads`, or Desktop, use `sftp download`.
- If the user says to create or modify a file on the remote host, use `sftp write`, `sftp upload`, or another remote SFTP operation. Do not reinterpret that as a local download.

## One-Off Commands

- List a directory:
  - `<netcatty-cli-prefix> sftp list --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
- Read a file:
  - `<netcatty-cli-prefix> sftp read --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
- Write a small text file with known content:
  - `<netcatty-cli-prefix> sftp write --session <session-id> --remote-path <remote-path> --content <text> --json --chat-session <chat-session-id>`
- Download a remote file to an existing local path:
  - `<netcatty-cli-prefix> sftp download --session <session-id> --remote-path <remote-path> --local-path <local-path> --json --chat-session <chat-session-id>`
- Upload an existing local file:
  - `<netcatty-cli-prefix> sftp upload --session <session-id> --local-path <local-path> --remote-path <remote-path> --json --chat-session <chat-session-id>`
- Delete a remote path:
  - `<netcatty-cli-prefix> sftp delete --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`

## Rules

- Use `sftp write` directly for creating or updating a small text file with known content.
- Use `sftp upload` only when a real local file already exists and must be transferred.
- Use `sftp download` when the result must be saved to the local filesystem.
- Do not create temporary local files just to upload text that could be sent with `sftp write`.
- Do not use `sftp read` as a substitute for `sftp download` when the user asked for a local saved file.
- Do not use `sftp write` as a substitute for `sftp download`; writing to `/tmp/foo` with `sftp write` writes to the remote host's `/tmp`, not the local machine.
- Do not use shell commands like `cat`, `touch`, redirection, or ad hoc SCP/SSH usage for remote file tasks.