Metadata-Version: 2.4
Name: probefs
Version: 0.1.0
Summary: A fast, beautiful, keyboard-driven TUI file browser
Project-URL: Homepage, https://github.com/diverdale/probefs
Project-URL: Repository, https://github.com/diverdale/probefs
Project-URL: Bug Tracker, https://github.com/diverdale/probefs/issues
Author-email: Dale Wright <diverdale@gmail.com>
License: MIT
License-File: LICENSE
Keywords: cli,file-browser,file-manager,miller-columns,sftp,terminal,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: fsspec>=2024.2.0
Requires-Dist: paramiko>=3.0.0
Requires-Dist: ruamel-yaml>=0.19.1
Requires-Dist: send2trash>=2.1.0
Requires-Dist: textual>=0.89.1
Description-Content-Type: text/markdown

# probefs

**A fast, beautiful, keyboard-driven TUI file browser built with Python and Textual.**
Navigate your filesystem at the speed of thought — no mouse required.

![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Framework](https://img.shields.io/badge/built%20with-Textual-purple)

---

## Layout

```
┌─────────────────────────────────────────────────────────────────────────┐
│  probefs                                                                │
├──────────────────┬──────────────────────┬──────────────────────────────┤
│  PARENT          │  CURRENT             │  PREVIEW                     │
│                  │                      │                              │
│  ..              │  > Documents/        │  # README.md                 │
│  home/           │    Downloads/        │                              │
│  etc/            │    Music/            │  Welcome to probefs.         │
│  usr/            │    Pictures/         │  A keyboard-driven TUI       │
│  var/            │    Videos/           │  file browser built with     │
│                  │    README.md         │  Python and Textual.         │
│                  │    .bashrc           │                              │
│                  │    .gitconfig        │  Navigate fast. No mouse.    │
│                  │                      │                              │
├──────────────────┴──────────────────────┴──────────────────────────────┤
│  ~/home/user  •  8 items  •  42.3 GB free                              │
├─────────────────────────────────────────────────────────────────────────┤
│  j/k move  l/Enter open  h/Back up  y copy  p move  d trash  ? help   │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Features

- **Three-pane miller columns** — parent context, active directory, and live preview side-by-side
- **Vim-style navigation** — `j`/`k` to move, `l` to enter, `h` to go up
- **Navigation history** — `Ctrl+O` / `Ctrl+I` to jump back and forward; `g` to go to any path
- **Syntax-highlighted previews** — powered by Pygments, auto-detected from file extension
- **Archive previews** — ZIP and tar file contents listed inline, no extra deps required
- **PDF previews** — extracted text preview via poppler (`pdftotext`), if installed
- **Directory previews** — right pane lists directory contents when a folder is selected
- **Sort modes** — `s` cycles name↑ → name↓ → size↓ → date↓; sort indicator in status bar
- **Fuzzy name filter** — `/` opens a live filter bar; type to narrow, `Enter` to keep, `Esc` to clear
- **Full file operations** — copy, move, rename, delete, new file, new directory
- **Safe deletes** — `d` sends to OS Trash, never permanent deletion
- **Open with default app** — `o` launches the system default application for a file
- **Clipboard** — `Y` copies the selected item's full path to the clipboard
- **Shell drop** — `!` drops to your `$SHELL` in the current directory; probefs resumes on exit
- **SFTP dual-pane** — `Ctrl+S` opens a local↔remote transfer screen; connection profiles saved automatically
- **Toggle hidden files** — `.` key shows/hides dotfiles instantly
- **Nerd Fonts icons** — optional glyph icons with `icons: nerd` in config (falls back to ASCII)
- **Configurable themes** — three built-ins plus a full custom theme YAML schema
- **Rebindable keys** — override any action's keybinding in your config file
- **Help dialog** — `?` shows the full keybinding reference at any time
- **Status bar** — always shows current path, item count, sort mode, and free disk space
- **Zero mouse required** — every operation reachable from the keyboard

---

## Requirements

- Python >= 3.10
- Any modern terminal (kitty, iTerm2, Ghostty, Windows Terminal, GNOME Terminal, etc.)
- **Optional:** [poppler](https://poppler.freedesktop.org/) for PDF previews (`brew install poppler` / `apt install poppler-utils`)

---

## Installation

### From PyPI (recommended)

```sh
pip install probefs
```

Or with [uv](https://github.com/astral-sh/uv) (installs as an isolated tool):

```sh
uv tool install probefs
```

### From source (development)

```sh
git clone https://github.com/yourusername/probefs.git
cd probefs
uv sync
uv run probefs
```

---

## Quick Start

```sh
probefs
```

That's it. probefs opens in your current directory.

---

## Key Bindings

### Navigation

| Key | Action |
|-----|--------|
| `j` / `↓` | Move cursor down |
| `k` / `↑` | Move cursor up |
| `l` / `Enter` | Enter directory / open file |
| `h` / `Backspace` | Go up to parent directory |
| `Ctrl+O` | Navigate back in history |
| `Ctrl+I` | Navigate forward in history |
| `g` | Go to path (jump anywhere) |

### View

| Key | Action |
|-----|--------|
| `.` | Toggle hidden files (dotfiles) |
| `s` | Cycle sort mode (name↑ → name↓ → size↓ → date↓) |
| `/` | Filter files by name (live; `Esc` cancel · `Enter` keep) |

### File Operations

| Key | Action |
|-----|--------|
| `y` | Copy selected item |
| `p` | Move selected item |
| `d` | Delete — sends to OS Trash (safe, reversible) |
| `r` | Rename selected item |
| `n` | New file in current directory |
| `Ctrl+N` | New directory in current directory |

### Clipboard & Launch

| Key | Action |
|-----|--------|
| `Y` | Copy current path to clipboard |
| `o` | Open with system default application |
| `!` | Drop to shell in current directory |
| `Ctrl+S` | Open SFTP screen |

### App

| Key | Action |
|-----|--------|
| `?` | Show help / keybinding reference |
| `a` | About probefs |
| `Ctrl+Q` / `Ctrl+C` | Quit |

---

## Configuration

probefs reads `~/.probefs/probefs.yaml` on startup. The file and directory are created automatically on first launch. For a fully commented reference, see [`probefs.yaml.example`](probefs.yaml.example) in this repo.

```yaml
# ~/.probefs/probefs.yaml

theme: probefs-dark          # built-in theme name
theme_file: ~/mytheme.yaml   # path to a custom theme YAML (overrides theme:)

icons: nerd                  # nerd (requires Nerd Fonts) | ascii (default)

keybindings:
  probefs.cursor_down: "j"   # override a default key
```

Invalid configuration is silently ignored; probefs will never crash on startup due to a bad config file.

---

## Themes

Three themes are built in:

| Theme name | Style |
|---|---|
| `probefs-dark` | Dark background, blue/teal accents (default) |
| `probefs-light` | Light background, high-contrast |
| `probefs-tokyo-night` | Tokyo Night color palette |

Activate a theme in your config:

```yaml
theme: probefs-tokyo-night
```

---

## Custom Themes

Drop a `.yaml` file into `~/.probefs/themes/` and probefs picks it up automatically on next launch. Activate it by name:

```yaml
theme: my-theme
```

Or point `theme_file` directly at any YAML file:

```yaml
theme_file: ~/my-probefs-theme.yaml
```

Full theme schema:

```yaml
name: my-theme           # required
dark: true               # true = dark background variant

# Core colors (all accept CSS hex, rgb(), or named colors)
primary:    "#5B8DD9"
secondary:  "#2D4A8A"
background: "#1C2023"
surface:    "#252B2E"
panel:      "#1E2528"
foreground: "#E0E0E0"
warning:    "#FFB86C"
error:      "#FF5555"
success:    "#50FA7B"
accent:     "#8BE9FD"

# Optional metadata (informational only, not used at runtime)
author:      "Your Name"
description: "My custom theme"
version:     "1.0.0"
```

Only `name` and `primary` are required. All other color fields are optional and fall back to theme defaults.

---

## Icons

By default probefs uses plain ASCII symbols that work in any terminal. If your terminal uses a [Nerd Fonts](https://www.nerdfonts.com/) patched font, enable glyph icons:

```yaml
icons: nerd
```

| Setting | Icons used |
|---------|------------|
| `ascii` (default) | `/` dirs, space files — works everywhere including SSH |
| `nerd` | Unicode glyphs from Nerd Fonts (requires patched font) |

> Auto-detection is not possible over SSH, so Nerd Fonts must be explicitly enabled.

---

## Keybinding Overrides

Override any action's key in `~/.probefs/probefs.yaml`:

```yaml
keybindings:
  probefs.cursor_down: "j,ctrl+j"   # multiple keys: comma-separated
  probefs.cursor_up:   "k"
  probefs.quit:        "q"
```

An override **replaces** all defaults for that action. To keep an existing key and add a new one, list both:

```yaml
keybindings:
  probefs.enter_dir: "l,enter,space"   # l, Enter, and Space all enter a directory
```

> Note: chord/sequence bindings (e.g. `gg`) are not supported. No conflict detection is performed — if two actions share a key, last registration wins.

---

## Documentation

Full reference: [docs/USER_GUIDE.md](docs/USER_GUIDE.md)

---

## License

MIT — see [LICENSE](LICENSE) for details.
