Repolode
Submit
andreafrancia

andreafrancia/trash-cli

Command-line tool that moves files to the freedesktop.org trashcan, the same trash used by KDE, GNOME and XFCE.

View on GitHub
Stars
4,612
Forks
213
Open issues
78
Last commit
3 days ago

What is it?

trash-cli lets you send files and directories to the freedesktop.org trashcan from the terminal instead of deleting them permanently. Each trashed item keeps its original path, deletion date and permissions, so it can be found and restored later.

The package installs five commands: trash-put to trash files, trash-list to list them, trash-restore to restore an item (including overwriting existing files and restoring several at once), trash-empty to empty the trashcan or remove only items older than a set number of days, and trash-rm to remove individual files matching a pattern. Because it uses the same trashcan as desktop file managers, items trashed here also appear in those applications.

The project is written in Python, installs via pipx, pip, or system package managers such as apt, pacman, dnf and Homebrew, and supports shell completions for bash, zsh and tcsh. It does not support Btrfs volumes.

Key features

  • 01Moves files to the freedesktop.org trashcan shared with KDE, GNOME and XFCE.
  • 02Records original path, deletion date and permissions for each trashed item.
  • 03Restores items interactively, with options to overwrite and select ranges.
  • 04Empties the trashcan entirely or only removes items older than N days.
  • 05Provides shell completions for bash, zsh and tcsh.

Use cases

  • Replacing rm in daily terminal work to keep accidental deletions recoverable.
  • Scheduling daily cleanup of old trashed files with cron.
  • Searching and restoring trashed files from scripts or the shell.

Quick start

  1. 1

    Install trash-cli with pipx (recommended)

    pipx install trash-cli
  2. 2

    Alternatively, install with pip

    pip install trash-cli
  3. 3

    Trash a file

    trash-put foo
  4. 4

    List trashed files

    trash-list

Things to know

  • Does not support Btrfs volumes.
  • Restore and list behavior depends on the freedesktop.org trash layout, so it works only where that trash is used.

Topics

#linux#trashcan#command-line#freedesktop#python#file-management

FAQ

What is trash-cli?
Command-line tool that moves files to the freedesktop.org trashcan, the same trash used by KDE, GNOME and XFCE. trash-cli lets you send files and directories to the freedesktop.org trashcan from the terminal instead of deleting them permanently. Each trashed item keeps its original path, deletion date and permissions, so it can be found and restored later.
Is trash-cli free to use? What license does it have?
trash-cli is open source under the GPL-2.0 license. Check the license terms before using it in commercial products.
Is trash-cli still maintained?
Actively maintained. The last commit to trash-cli was on Oct 16, 2026.
What can I use trash-cli for?
Replacing rm in daily terminal work to keep accidental deletions recoverable. Scheduling daily cleanup of old trashed files with cron. Searching and restoring trashed files from scripts or the shell.
How do I install trash-cli?
Install trash-cli with pipx (recommended): pipx install trash-cli Alternatively, install with pip: pip install trash-cli Trash a file: trash-put foo List trashed files: trash-list
Where can I get trash-cli?
The source code and installation instructions are on GitHub: https://github.com/andreafrancia/trash-cli

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects