ferp 0.13.0

Terminal-first file navigator and FSCP automation workbench built with Textual.

---

About

FERP is a terminal-friendly file manager and automation workbench. It combines an interactive file navigator and a protocol-driven script runner so you can explore directories and execute repeatable workflows through a TUI—without requiring terminal knowledge.

Highlights

• Keyboard-first navigation
  • A full list of keys are available in the app.
• Context panes
  • Script list reads from the user config config.json (platformdirs).
  • Output panel streams FSCP results and records transcripts under the user data logs directory.
  • README modal (Enter on a script) displays bundled documentation.
• Visual mode (multi-select)
  • Select multiple items in the file navigator, including range selection.
  • Copy, move, paste, and delete selected files or folders without running scripts.
  • Scripts/output panels are disabled while visual mode is active.
• Managed script runtime
  • Scripts execute via the FSCP host ↔ script protocol.
  • Interactive prompts, confirmations, progress, and structured results are supported.
  • Logs are timestamped and automatically pruned (default 50 files / 14 days).

Quick Start

pipx install ferp

[!NOTE] To use the default scripts, open the command palette (Ctrl+P) and select Install/Update Default Scripts.

[!WARNING] This option is intended for specific users. It will remove any existing scripts you have installed.

If you prefer to install scripts individually, or to use your own custom scripts, see FSCP.

Configuring Scripts

Scripts are declared in your user config config.json (created on first script install). Each entry defines:

• script: path to the executable (e.g. scripts/ferp.zip_dir/script.py).
• target: current_directory, highlighted_file, or highlighted_directory.
• file_extensions: optional list of suffixes (for highlighted_file targets).
• Optional README at scripts/<id>/readme.md.

Each script lives under scripts/<id>/ (the directory name matches the fully-qualified ID, such as ferp.zip_dir). Inside the directory:

• script.py contains the executable FSCP script.
• readme.md provides the optional documentation shown inside FER​P.

Namespaces are only required for bundled/default scripts and for the repo dev setup. Custom scripts can stay in the single user config.json without a namespace.

Dev toggle for script config

During development you can point FER​P at the repo copy of ferp/scripts/config.json instead of the user config file:

FERP_DEV_CONFIG=1 textual run --dev ferp/app.py

When enabled, FER​P reads the repo configs directly: ferp/scripts/config.json plus any ferp/scripts/<namespace>/config.json files, and skips the one-time copy into the user config directory. Script update notifications are suppressed while FERP_DEV_CONFIG=1 is set.

Scripts that log data with debug level are skipped by default. You can enable these logs by adding the debug flag:

FERP_DEV_CONFIG=1 FERP_SCRIPT_LOG_LEVEL=debug textual run --dev ferp/app.py

Configuration

FERP uses two configuration layers:

• Runtime config (env): FERP_* environment variables (preferred for automation).
• User settings (file): settings.json in the user config directory (managed by the app).

Precedence order: env -> settings.json -> defaults.

Runtime env vars:

• FERP_DEV_CONFIG=1 to read script configs from the repo during development.
• FERP_SCRIPT_LOG_LEVEL=debug to include debug logs from FSCP scripts.

You can inspect the resolved configuration with:

ferp print-config

Settings are versioned with schemaVersion and automatically normalized on load. If an upgrade is detected, a backup is created next to settings.json with a settings.bak-YYYYMMDDHHMMSS.json suffix.

Logs are separated by type under the user data directory:

• logs/host/host.log for UI/host application logs.
• logs/scripts/ for per-script transcript logs.

Error Codes

When operations fail, FER​P emits structured error codes for easier support and troubleshooting. Example codes you may see:

• release_metadata_failed, release_asset_download_failed
• namespaces_missing_list, namespaces_missing_namespace
• monday_api_error, monday_board_not_found

Authoring FSCP Scripts

Python scripts executed from FER​P speak the FSCP protocol. See SCRIPT_AUTHORS.md for the SDK guide, examples, logging, cancellation, cleanup, and packaging details.

Terminal Commands

FERP opens your system terminal in the current directory (shown in the top bar).

• Open a terminal using Ctrl+t.
• The spawned terminal inherits the current working directory.
• On Windows system, prefers PowerShell and falls back to CommandPrompt.

Task List

FERP includes a lightweight task list for quick capture and review.

• Press t to add a task from anywhere in the UI.
• Press l to open the task list and review or mark tasks as complete.
• Tag tasks with @ for text highlighting and filtering.
• Toggle completion status with the space bar.
• The task status indicator updates automatically as tasks are completed.

Other Features

• Default script updates: Pull the latest default scripts from the release feed (suppressed in dev mode).
• Process list: View and stop running scripts from the command palette.
• Tasks: Capture quick tasks and review them in the task list.
• Themes: Switch themes from the command palette.
• Startup directory: Set the default path Ferp opens on launch.
• Logs: Open the latest transcript log from the command palette.