Metadata-Version: 2.4
Name: scp-browser-tui
Version: 0.2.1
Summary: Keyboard-driven TUI browser for remote SSH/SFTP downloads
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual<0.70,>=0.58
Requires-Dist: paramiko<4.0,>=3.4
Requires-Dist: keyring<26.0,>=25.0
Requires-Dist: platformdirs<5.0,>=4.2
Dynamic: license-file

<h1 align="center">SCP Browser TUI</h1>

<p align="center">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  <a href="https://www.python.org/"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue"></a>
  <a href="#features"><img alt="Platform" src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-green"></a>
  <a href="https://textual.textualize.io/"><img alt="UI" src="https://img.shields.io/badge/TUI-Textual-5c4ee5"></a>
  <a href="https://www.paramiko.org/"><img alt="SSH" src="https://img.shields.io/badge/SSH-Paramiko-2ea44f"></a>
  <a href="#one-command-install"><img alt="Install with pipx" src="https://img.shields.io/badge/install-pipx-f69220"></a>
</p>

<p align="center">
  <code>scp-browser-tui</code> is a keyboard-driven terminal file browser for downloading files from remote Linux systems over SSH/SFTP. It uses Textual for the interface, Paramiko for SSH/SFTP operations, and keyring for password storage when available.
</p>

## Features

- Connection screen for creating, editing, deleting, and reusing saved profiles
- Password and SSH key authentication with keyring-backed secret storage where available
- Two-pane local and remote file browser with keyboard navigation
- Live preview panel for the currently highlighted local or remote item
- File metadata display: name, type, size, modified time
- Download of files and directories
- Upload of local files and directories into the current remote folder
- Queued upload and download progress with overall progress feedback
- Safe remote rename, move, mkdir, and delete operations
- Auto-rename handling for local and remote name conflicts
- Local and remote pane filtering
- Hidden-file toggle and sort cycling
- Per-profile last visited remote path and default local download directory

## Screenshots

### Connection Screen

![Connection screen](assets/connect-screen.png)

### Connection Screen Variant

![Connection screen variant](assets/connect-screen-1.png)

### File Browser

![File browser](assets/file-browser.png)

## Project Layout

```text
ftransfer/
├── CHANGELOG.md
├── README.md
├── requirements.txt
├── pyproject.toml
├── ftransfer.cmd
├── ftransfer.ps1
├── examples/
│   └── profiles.example.json
└── src/
    └── scp_browser/
        ├── __init__.py
        ├── __main__.py
        ├── app.py
        ├── config.py
        ├── download_manager.py
        ├── models.py
        ├── profile_manager.py
        ├── secrets.py
        ├── ssh_client.py
        └── screens.py
```

## Installation

1. Create and activate a virtual environment.
2. Install dependencies:

```bash
pip install -r requirements.txt
```

To install the `ftransfer` command:

```bash
pip install -e .
```

## One-Command Install

Recommended with `pipx`:

```bash
pipx install git+https://github.com/patchharris/ftransfer.git
```

Fallback with `pip`:

```bash
pip install "scp-browser-tui @ git+https://github.com/patchharris/ftransfer.git"
```

## Run

From the project root:

```bash
PYTHONPATH=src python -m scp_browser
```

Windows PowerShell:

```powershell
$env:PYTHONPATH="src"
python -m scp_browser
```

Linux / macOS:

```bash
export PYTHONPATH=src
python -m scp_browser
```

After `pip install -e .`, you can launch it directly with:

```bash
ftransfer
```

From this repo folder on Windows, you can also use:

```powershell
.\ftransfer.ps1
```

Linux example:

```bash
git clone https://github.com/patchharris/ftransfer.git
cd ftransfer
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
ftransfer
```

## Keyboard Shortcuts

### Connection screen

- `Tab` / `Shift+Tab`: move between fields
- `Ctrl+S`: save profile
- `Ctrl+N`: clear form for a new profile
- `Delete`: delete selected profile
- `F5`: connect with current form values
- `Enter`: submit a form field and connect
- `F1`: open the in-app changelog/about screen
- `q`: quit

Connection form notes:

- Use the `Password` / `SSH Key` toggle buttons to choose auth mode
- `password` field is also used for an SSH key passphrase
- `key path` is required when auth type is `key`

### Browser screen

- `Tab`: switch between local and remote panes
- `Enter`: open selected directory in the active pane
- `Backspace` or `h`: go to parent directory in the active pane
- `p`: toggle the preview panel
- `/`: set or clear a filter for the active pane
- `r`: refresh both panes
- `.`: toggle hidden files
- `s`: cycle sort order
- `F1`: open the in-app changelog/about screen
- `q`: disconnect and return to the connection screen

### Remote pane actions

- `Space`: toggle multi-select
- `d`: download selected items, or current item if none are marked
- `m`: create a remote directory in the current remote folder
- `v`: move the selected remote item to a new name or path
- `n`: rename selected remote item
- `x`: delete selected remote item

Delete confirmation:

- file delete: type `y` and press `Enter`
- directory delete: type `delete` and press `Enter`

### Local pane actions

- `u`: upload selected local file or directory into the current remote folder

Preview panel:

- Updates automatically as you move through either pane
- Shows metadata for files and directories
- Shows a small text preview for UTF-8 text files
- Marks binary files and truncated previews clearly

## Profiles and Secrets

Profiles are stored as JSON in the per-user config directory:

- Linux: `~/.config/scp-browser-tui/profiles.json`
- Windows: `%APPDATA%\scp-browser-tui\profiles.json`

Passwords are not written into `profiles.json`. The app stores them in the system keyring under the `scp-browser-tui` service name when the keyring backend is available. If keyring is unavailable, the password field remains session-only and the secret handling is isolated in `src/scp_browser/secrets.py`.

## Example Profile File

See [examples/profiles.example.json](/C:/Users/patch/Coding/ftransfer/examples/profiles.example.json).

## Notes

- The app uses SFTP for directory browsing and downloads. It does not shell out to `scp`.
- It targets Python 3.11+.
- The browser is now two-pane: local on the left, remote on the right.
- If a destination name already exists, uploads and downloads auto-rename rather than prompting.
- Transfers now run through a file queue and show overall progress across multi-file operations.

## Future Enhancements

- Search within the current directory
- Remote folder bookmarks
- Local destination picker with bookmarks/history
- Host key verification management UI

## License

MIT. See [LICENSE](/C:/Users/patch/Coding/ftransfer/LICENSE).
