trash-cli: Reversible File Removal from the Command Line

Why trash-cli Avoids Permanent Shell Deletion

trash-cli addresses a specific command-line failure mode: selecting the wrong file or directory for permanent deletion. The README contrasts it with `rm`, which permanently deletes files. Instead, trash-cli moves the selected items to the trash, which the README describes as safer and reversible.

The command is for developers, system administrators, and other people who remove files from terminals. Its path and glob interfaces suit project artifacts, downloaded images, generated files, and entire directories. It may also fit users who do not want to open a desktop trash interface for every command-line deletion. The central distinction is not different matching or automation. It is the destination: the operating system's trash instead of irreversible removal through `rm`.

The README states that trash-cli works on macOS 10.12 or later, Linux, and Windows 8 or later. It does not document behavior on older Windows releases or older macOS versions. It also does not explain how remote servers, mounted filesystems, or shared network storage behave. Those omissions matter because a trash operation does not establish what happens to files stored on every possible volume.

The package is a command rather than an importable application API. `package.json` registers the executable name as `trash` and maps it to `cli.js`. The related `trash` package is described by the README as an API for this package, but the installation documented for trash-cli is a global npm installation of `trash-cli`.

How trash-cli Handles Paths, Globs, and Options

The documented command accepts paths and glob patterns. A user can name several files in one invocation, pass a pattern that matches a broader set, or combine a positive pattern with a negated pattern. The README example `trash '*.png' '!unicorn.png'` shows both the intended set and an exclusion.

Glob behavior has one explicit option. Without `--dot`, the README says the command will not match dotfiles when using glob patterns. With `--dot`, dotfiles can participate in matching. This distinction matters in repositories and configuration directories where hidden entries can be operationally significant. The README also warns users to remember quoting the glob, and its examples use single quotes. Preserving the quoted pattern gives the command a defined input rather than relying on the user's shell to expand it first.

The repository dependencies clarify the broad implementation path. `package.json` declares `globby` for the documented glob dependency, `meow` for command-line parsing, and `trash` for the trash operation. The package uses ES modules through `"type": "module"`, while the `bin` entry exposes `./cli.js` as `trash`. The README does not expose the command's internal parsing sequence, so the exact handling of malformed paths, unmatched patterns, duplicates, and conflicting matches is not documented here.

Output is documented as human-readable terminal output. The `--verbose, -v` option prints trashed items. The README does not promise JSON output, stable ordering, detailed error codes, confirmation prompts, or an exit-code table. Those omissions matter for automation. Moving a file to a recoverable destination does not make every shell-script concern disappear.

Installing trash-cli and Trying Its First Commands

The project documents a global npm installation. `package.json` requires Node.js 20 or later, so the runtime version should be checked before installing the package. The global npm installation makes the `trash` executable available through the user's command path.

Run the documented installation command:

npm install --global trash-cli

The README then directs users to inspect the command's built-in help:

trash --help

The documented output identifies the usage as `trash <path|glob> […]` and lists `--dot` and `--verbose, -v`. The help also describes `--verbose` as printing trashed items. Users should confirm that the global npm command directory is available to their terminal. The README does not document troubleshooting for a shell that cannot find `trash`.

A first real use can name two files. The README gives this exact example:

trash unicorn.png rainbow.png

The command moves the named items to the trash. For matching PNG files while excluding one file, the README gives this quoted glob example:

trash '*.png' '!unicorn.png'

The quotes are significant because the README explicitly says to remember quoting glob patterns. The separate `--dot` option changes whether hidden files are included in pattern matching. The help output documents the short form `-v` for verbose item printing, but the README does not provide a separate end-to-end example that combines `--dot` and `-v`. No such combined command should be assumed without consulting the command's own output.

The `rm` Alias Offers Safety Inside Interactive Shells

The README recommends adding `alias rm=trash` to `.zshrc` or `.bashrc`. Its stated purpose is to reduce typing while sending deletion requests to the trash. After adding the alias to a shell configuration, the README gives this example:

rm unicorn.png

This is an interactive convenience, not a transparent replacement for Unix `rm`. The alias must be loaded by the shell configuration, and the README does not say that it affects noninteractive execution, subprocesses, editor commands, scripts, or programs that resolve an executable without consulting shell aliases. Those boundaries make the alias useful for personal shell use but unsuitable as the only documented protection for automation.

The suggestion also changes semantics. The documented `trash` interface lists paths, globs, `--dot`, and `--verbose`, while traditional `rm` has its own command-specific behavior. The README does not present a compatibility mapping between the two interfaces. Users should therefore avoid assuming that every familiar `rm` invocation behaves correctly after adding the alias.

A shell alias is also local configuration. A different machine or CI runner may use the real `rm` even when a developer has configured the alias. For project scripts, the README does not document a setting that forces `trash-cli` or declares it as a replacement. Teams that need a shared deletion policy need more than this personal shell recommendation.

Where trash-cli Is the Wrong Tool

trash-cli is the wrong choice when deletion must be permanent. The README lists `del-cli` for deleting files and folders, while its own purpose is to move items to the trash. A script that requires immediate removal, cleanup of files that must never remain recoverable, or predictable handling of storage volume should not silently substitute a trash operation.

The project is also outside its documented platform range on macOS older than 10.12 and Windows older than 8. Linux is listed without further platform-specific requirements. The README does not address headless Linux installations, desktop trash specifications, mounted volumes, or network shares. A user moving files on such systems needs direct verification rather than assuming the macOS and Windows behavior also applies.

The README does not document restoration commands, retention periods, trash quotas, or recovery guarantees. It links to `empty-trash-cli` for emptying the trash, which reinforces that emptying is a separate action. It also does not document rollback after the trash is emptied. For data recovery or compliance workflows, those missing details are functional requirements, not small documentation omissions.

There is another practical boundary: glob mistakes can select more files than intended. The `--dot` switch expands matching to hidden entries, and shell quoting affects how patterns reach the command. The README supplies examples but no interactive preview before deletion. Users who need review of a large match should verify the target paths outside trash-cli before applying a broad pattern.

trash-cli, del-cli, and Shell `rm` Serve Different Intentions

The README gives three distinct choices. `rm` permanently deletes files, `trash-cli` moves files and folders to the trash, and `del-cli` is listed for deleting files and folders. The alternative here is not simply another package with a different command name. The destination and reversibility differ.

For personal command-line work where an item may be needed again, trash-cli removes the file from its current location while retaining it in the system trash. For cleanup that must complete deletion, del-cli is the documented related tool. For built-in shell behavior that is expected to be permanent, `rm` remains the direct choice. None should be treated as interchangeable in a script merely because all three accept filesystem paths.

The README's `alias rm=trash` suggestion bridges the personal workflow, but it does not merge command-line semantics. It redirects the shell command after the alias is loaded and does not document compatibility with `rm` options. The appropriate choice therefore depends on whether recoverability is desired, which platform handles the trash, and whether the caller is an interactive shell or a noninteractive process.

The repository layout supports a small package rather than a broad deletion suite. `package.json` lists only `cli.js` in the published `files` array and points the `trash` executable to that file. The related projects remain separate tools, so an adoption decision should not assume that trash-cli also provides permanent deletion, trash restoration, or trash emptying.

License, Releases, and Upgrade Requirements

The repository uses the MIT license. The available repository information identifies the package as `sindresorhus/trash-cli`, and `package.json` names Sindre Sorhus as author. The README and repository metadata also include a funding link. These facts describe the package's licensing and attribution context, but they do not replace review of the actual license text for a particular deployment.

The repository is not archived. Its last push was on 2026-09-18. The listed releases are v7.2.0 on 2026-02-02, v7.1.1 on 2026-01-26, and v7.1.0 on 2026-01-25. The recent push date and release dates show that the repository has current activity, but the README does not provide upgrade instructions, migration notes, or a compatibility table for those versions.

`package.json` declares Node.js `>=20`, which is a concrete adoption constraint for environments running older Node.js releases. Runtime dependencies include `globby`, `meow`, and `trash`. Test dependencies include `ava`, `execa`, `path-exists`, `temp-write`, and `xo`, with the test script set to `xo && ava`.

The package metadata does not specify a lockfile policy for consumers. Caret ranges are used for dependencies, so exact resolution belongs to the npm installation and the consumer's dependency setup. Before changing a shell alias or production wrapper, users should inspect the new release and verify the installed executable. The README gives no rollback command, so upgrade planning cannot be based on a documented rollback procedure.

Editorial conclusion

Developers and everyday command-line users should consider trash-cli when a deletion workflow through the operating system's trash fits the target machines. Users requiring permanent deletion, unattended recovery assumptions, or unsupported operating-system versions need another approach. Verify Node.js 20 or later, platform behavior, glob quoting, and the consequences of any `rm` alias before adopting it for routine scripts.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sindresorhus/trash-cli on GitHub