How do I install oops?

Run: curl -fsSL oops-cli.com/install.sh | bash. The installer downloads the binary, adds the shell hook, and creates the backup directory automatically.

How do I undo a deleted file in the terminal?

If oops is installed, just type 'oops' to restore the last deleted file. Use 'oops 2' to go further back. oops automatically backs up files before rm, mv overwrites, sed -i, git reset --hard, and other destructive commands.

How do I uninstall oops?

Run 'oops uninstall' to remove the shell hook and backup directory, then run 'sudo rm /usr/local/bin/oops' to remove the binary.

What shells does oops support?

oops supports zsh, bash, and fish. It uses each shell's native preexec mechanism.

How much disk space does oops use?

Backups auto-clean after 2 hours by default. Maximum trash size is 25GB. You can lower the cap via 'oops config'. Run 'oops size' to check current usage and 'oops clean' to free space.

Documentation

Installation, shell setup, commands, and configuration.

Installation

One-liner (macOS and Linux). The installer discovers the latest GitHub Release, verifies checksums, checks Sigstore signatures when cosign is available, offers an arrow-key protection profile picker, repairs local backup directory ownership when needed, and runs a restore self-test:

curl -fsSL oops-cli.com/install.sh | bash

Homebrew support is ready for the public tap:

brew install gedaliahs/tap/oops

From source (requires Go):

git clone https://github.com/gedaliahs/oops.git cd oops && go build -o oops . sudo mv oops /usr/local/bin/

Shell setup

Add one of these to your shell config, then restart:

# zsh (~/.zshenv) eval "$(oops init zsh)" # bash (~/.bashrc) eval "$(oops init bash)" # fish (~/.config/fish/config.fish) oops init fish | source

Run oops doctor to verify.

Usage

# undo last action oops # undo second-to-last oops 2 # undo third oops 3 # preview without changing files oops undo --dry-run oops restore --plan

Commands

oops

Undo the last destructive action. Pass a number to go further back. If the restore target already exists, choose --overwrite, --backup-current, or --to DIR. Use oops undo --dry-run or oops restore --plan to see conflicts, backup-current paths, overwrite behavior, and git actions before changing files.

oops status

Show installed version, hook state, undoable entries, trash size, retention, and protected-path counts.

oops log

Show undo history. -n 50 for more.

oops show

Preview the command, files, or git recovery action that oops would restore.

oops diff

Compare the saved backup with the current file or directory before restoring.

oops keep / oops unkeep

Keep a backup from automatic cleanup, or allow it to be cleaned up again.

oops size

Show backup disk usage.

oops clean

Remove old backups. --all for everything, --older-than-hours 3 for entries older than 3 hours.

oops cleanup-service

Install, uninstall, or inspect an hourly background cleanup job using launchd on macOS or systemd user timers on Linux.

oops config

View or set settings:

oops config # show all oops config retention_hours 6 # keep 6 hours oops config max_trash_bytes 10737418240 # lower cap to 10 GB oops config risk_warning false # disable warnings oops config preset agent # normal, agent, cautious, quiet

oops protect-path

Add high-safety rules for important files or folders. Matching actions are treated as high risk and can keep backups longer.

oops protect-path ~/work --always-confirm --retention-hours 24 oops protect-path --list oops protect-path --remove ~/work

oops doctor

Health check — verifies directory, config, git, and hook. Use oops doctor --fix to repair common local permission problems.

oops init <shell>

Print the hook for zsh, bash, or fish.

oops tutorial

Interactive walkthrough — creates a test file, deletes it, and restores it to show you how oops works.

oops --upgrade

Upgrade to the latest version by re-running the installer.

oops --version

Print the installed version.

Configuration

Stored in ~/.oops/config.json:

retention_hours — hours to keep backups (default: 2)
max_trash_bytes — max trash size (default and maximum: 25 GB; can be lowered)
risk_warning — warn on high-risk commands (default: true)
confirm_mode — confirmation prompts: off, high, or all
protected_paths — high-safety path rules with optional longer retention

Storage

~/.oops/ config.json # settings journal.jsonl # action log trash/ 20260315-143022-a1b2/ manifest.json # metadata files/ # backed up files

Auto-cleanup runs lazily, at most once per hour. You can also install oops cleanup-service install for hourly cleanup in the background. Old entries get purged after the retention window. If trash exceeds the configured cap, oldest go first. The default and maximum cap is 25 GB.

Kept entries and active protected-path entries are skipped by automatic cleanup and size pruning. Use oops keep or oops protect-path for work you want to preserve longer than the default window.

How it works

Shell hook — a preexec function pattern-matches your command. Safe commands (ls, cat, git log, etc.) pass through with zero overhead — no subprocess is spawned.

Protect — for destructive commands, oops parses the command string, identifies the target files, and backs them up to ~/.oops/trash/. It catches direct commands plus common cleanup wrappers like xargs rm, fd -x rm, parallel rm, make clean, and package-manager clean scripts. Then the original command runs normally.

Undo — reads the journal, builds a restore plan, detects conflicts before mutating files, stages backup content, and restores files to their original paths or another directory with --to. For git ops, it applies the recorded stash SHA or recreates the deleted branch.

How backups work

oops copies files into ~/.oops/trash/ and writes a manifest for each journal entry. Copies use more disk than hard links, but they preserve the original content for overwrites, redirects, and in-place edits.

When you run oops to restore, the saved copy is written back to the original path. If a file already exists there, use --overwrite, --backup-current, or --to DIR. Use --plan first when you want an exact preview.

Uninstall

oops uninstall

Walks you through removing the shell hook, backup directory, and binary with y/n prompts.