Installation

Quick Install

git clone https://github.com/SkyCMD-Labs/VirusTotal-ShellHelper.git
cd VirusTotal-ShellHelper
./install.sh

The installer handles everything interactively.

Tip

The installer will automatically detect your system and download the vt CLI if needed.

Manual Installation

1. System Check — detects your architecture, distro, desktop environment, and file manager
2. Dependency Check — verifies required tools are installed
3. vt CLI Installation — downloads from GitHub releases if not found
4. vt-check Installation — copies script to ~/.local/bin/
5. Context Menu Setup — installs file manager integration

Manual Installation

1. Install Dependencies

Required:

# Arch/CachyOS
sudo pacman -S jq

# Ubuntu/Debian
sudo apt install jq

# Fedora
sudo dnf install jq

Optional (for notifications):

# Most distros have one of these
sudo pacman -S libnotify    # provides notify-send
sudo pacman -S dunst        # provides dunstify

2. Install VirusTotal CLI

Download from GitHub releases:

# Example for Linux x86_64
wget https://github.com/VirusTotal/vt-cli/releases/latest/download/Linux64.zip
unzip Linux64.zip
chmod +x vt
mv vt ~/.local/bin/

3. Configure API Key

vt init

Important

You must run vt init to configure your API key before using vt-check.

Get a free API key at: https://www.virustotal.com/gui/my-apikey

4. Install vt-check

cp vt-check ~/.local/bin/
chmod +x ~/.local/bin/vt-check

5. Add to PATH (if needed)

If ~/.local/bin isn't in your PATH:

# bash (~/.bashrc)
export PATH="$HOME/.local/bin:$PATH"

# zsh (~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# fish (~/.config/fish/config.fish)
fish_add_path $HOME/.local/bin

6. Install Context Menu (Optional)

See File Manager Integration for manual setup.

Verifying Installation

# Check vt-check is available
which vt-check

# Check vt CLI is configured
vt version

# Test on any file
vt-check --notify /usr/bin/ls

Uninstallation

Automated Uninstall (Recommended)

./uninstall.sh

The uninstaller will:

1. Remove all installed scripts (vt-check, vt-actions.sh, vt-manage)
2. Remove context menu integrations for all file managers
3. Optionally remove quarantine files and audit logs
4. Optionally remove tmpfs mount (if configured)

Manual Uninstallation

If you need to remove components manually:

# Remove scripts
rm ~/.local/bin/vt-check
rm ~/.local/bin/vt-actions.sh
rm ~/.local/bin/vt-manage

# Remove context menus (varies by file manager)
rm ~/.local/share/kio/servicemenus/vt-check.desktop          # Dolphin
rm ~/.local/share/nemo/actions/vt-check*.nemo_action         # Nemo
rm ~/.local/share/nautilus/scripts/Scan\ with\ VirusTotal*   # Nautilus
# For Thunar, manually edit ~/.config/Thunar/uca.xml

# Remove quarantine and audit data (optional)
rm -rf ~/.local/share/virustotal-quarantine
rm -rf ~/.local/share/virustotal-shell

# Remove tmpfs mount (if configured)
sudo systemctl disable home-$(systemd-escape "$USER")-.local-share-virustotal\\x2dquarantine.mount
sudo systemctl stop home-$(systemd-escape "$USER")-.local-share-virustotal\\x2dquarantine.mount
sudo rm /etc/systemd/system/home-$(systemd-escape "$USER")-.local-share-virustotal\\x2dquarantine.mount
sudo systemctl daemon-reload

The vt CLI and its config (~/.vt.toml) can be kept for other uses.