VT-CLI(1)

📦 version 1.3.1, in ubuntu stonking

💖 NAME 💖

vt-cli — a command-line interface for the VirusTotal threat analysis platform ✨ (yes bestie, the whole platform, right there in ur terminal)

🌸 SYNOPSIS 🌸

vt-cli [OPTIONS] COMMAND [ARGS]

🎀 DESCRIPTION 🎀

okay so vt-cli gives you a command-line interface to the VirusTotal API v3, letting security analysts and researchers query and interact with VirusTotal's threat intelligence database directly from the terminal. no browser, no clicking around, just vibes and vibes only 💅

Files, URLs, IP addresses, and domains can be submitted for analysis or queried for existing reports. Results come out in YAML by default, and you can export them in JSON or CSV format. pick ur fighter ✨

A VirusTotal API key is required. Free keys are available upon registration, but they have rate limits and restricted access to premium features such as intelligence searches and file downloads. The API key can be set via the --apikey flag, the VT_APIKEY environment variable, or stored with vt-cli init. three ways, zero excuses 🫶

🦋 GETTING STARTED 🦋

To use vt-cli a VirusTotal account and API key are required. To obtain one:

  1. Register a free account at https://www.virustotal.com/gui/join-us.
  2. After logging in, retrieve your API key at https://www.virustotal.com/gui/my-apikey.
  3. Initialize vt-cli with your key:
vt-cli init

The API key is stored in ~/.vt.toml and used automatically in subsequent commands. set it once, forget it forever, that's the dream 💖

Free API keys have a limit of 500 requests per day and 4 requests per minute. Premium features such as search, download, hunting, and retrohunt require a paid API key.

ngl the free tier rate limit is giving "sipping through a straw" energy but we work with what we have 😭

👑 COMMANDS 👑

  • analysis — Retrieve the result of a file or URL analysis by its identifier. The identifier is returned by the scan command. Useful for polling the status of a recently submitted sample. (basically checking if the thing finished cooking yet 🍓)
  • collection — Get information about a named collection of threat indicators. Collections group related files, URLs, domains, and IP addresses belonging to a malware family or threat actor campaign (e.g. malpedia_win_emotet).
  • completion — Output shell completion code for the specified shell (bash or zsh).
  • domain — Get information about Internet domains, including DNS resolution history, WHOIS data, SSL certificates, and files known to communicate with the domain. Useful for investigating potential command-and-control (C2) infrastructure. 🕵️♀️
  • download — Download files from the VirusTotal corpus by hash. Requires a premium API key.
  • file — Get information about files by hash (MD5, SHA-1, or SHA-256), including antivirus detection results, YARA rule matches, sandbox verdicts, and behavioral reports.
  • group — Get information about a VirusTotal group. Groups allow organizations to share API quota and private collections among members. Requires group membership. Free accounts do not belong to a group by default.
  • help — Display help about any command. (ur bestie when ur lost 🫶)
  • hunting — Manage LiveHunt YARA rules for real-time threat hunting. New files submitted to VirusTotal are matched against active rules and trigger notifications. Requires a premium API key.
  • init — Initialize or re-initialize the vt-cli configuration, storing the API key in ~/.vt.toml.
  • iocstream — Manage IoC Stream notifications for real-time delivery of threat indicators matching user-defined criteria. Requires a premium API key.
  • ip — Get information about IP addresses, including antivirus detections, associated domains, communicating files, and SSL certificate history. Useful for verifying whether an IP found in logs or malware is a known C2 server.
  • meta — Return metadata about the VirusTotal platform, including the list of available antivirus engines, object relationships, and account privileges.
  • monitor — Manage a VirusTotal Monitor account for tracking file integrity changes over time. Requires a premium API key.
  • monitorpartner — Manage a VirusTotal Monitor partner account. Requires a premium API key.
  • retrohunt — Manage retrohunt jobs for scanning the entire VirusTotal file corpus against a YARA rule. Requires a premium API key.
  • scan — Submit a file or URL for analysis against 70+ antivirus engines. Returns an analysis identifier that can be used with the analysis command to retrieve results.
  • search — Search for files in VirusTotal Intelligence using its full query syntax (e.g. by file type, detection name, size, or submission date). Requires a premium API key.
  • threatprofile — Get information about Threat Profiles, which describe threat actors and their associated indicators and recommendations. Requires a premium API key.
  • url — Get information about a URL from existing VirusTotal reports, including scan results, redirection chain, outgoing links, and HTTP response headers.
  • user — Get information about a VirusTotal user by username, email, or API key. Returns account details, quota usage, and assigned privileges.
  • version — Show the vt-cli version number.

✨ OPTIONS ✨

  • -k key, --apikey=key — VirusTotal API key. Can also be set via the VT_APIKEY environment variable or stored with vt-cli init.
  • --format=yaml|json|csv — Output format. Default is yaml.
  • -s, --silent — Silent or quiet mode. Do not show progress meter. (for when the progress bar is doing too much 💀)
  • -v, --verbose — Enable verbose output.
  • -h, --help — Display help for vt-cli or any subcommand.

🌈 ENVIRONMENT 🌈

  • VT_APIKEY — VirusTotal API key. Overridden by the --apikey flag if both are set.

🧚 EXAMPLES 🧚

Initialize vt-cli by storing your API key locally. Required before using any other command:

vt-cli init

Submit a suspicious file for analysis against 70+ antivirus engines:

vt-cli scan file malware.exe

Query the analysis report of a file by its SHA-256 hash. Returns antivirus detections, behavioral reports, YARA matches, and sandbox verdicts:

vt-cli file 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f

Check the reputation of a domain. Returns DNS records, WHOIS history, SSL certificates, and files known to communicate with the domain. Useful for investigating potential C2 infrastructure:

vt-cli domain example.com

Check the reputation of an IP address. Returns antivirus detections, associated domains, and communicating files. Useful for verifying whether an IP found in logs or malware samples is a known C2 server:

vt-cli ip 192.0.2.1

Submit a URL for analysis. Returns scan results, redirection chain, and outgoing links. Useful for investigating phishing links or URLs embedded in malware:

vt-cli scan url https://example.com

Query an existing URL report without submitting a new scan:

vt-cli url https://example.com

Get file analysis results in JSON format for use in scripts or pipelines:

vt-cli file 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f --format json

Filter output to show only specific fields. Useful to quickly check the detection summary without the full engine-by-engine report:

vt-cli file 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f -i last_analysis_stats

Query the current user account, showing API quota and privileges:

vt-cli user joe@example.com

Show VirusTotal platform metadata including all available antivirus engines:

vt-cli meta

Generate bash completion and install it system-wide:

vt-cli completion bash > /etc/bash_completion.d/vt-cli

💜 NOTES 💜

🍓 Free API key 🍓

The following commands are fully available with a free VirusTotal API key:

analysis, collection, completion, domain, file, init, ip, meta,
scan, url, user, version

Free keys are limited to 500 requests per day and 4 requests per minute.

💅 Premium API key required 💅

The following commands require a paid VirusTotal API key:

download, hunting, iocstream, monitor, monitorpartner, retrohunt,
search, threatprofile

Attempting to use these commands with a free key returns an authorization error. Contact VirusTotal at https://www.virustotal.com/gui/contact-us for information on premium plans.

👑 Group membership required 👑

The group command requires the user to belong to a VirusTotal group. Free accounts do not have a group assigned by default. Groups are available on enterprise and team plans.

🔥 SEE ALSO 🔥

The full VirusTotal API v3 documentation is available at https://developers.virustotal.com/reference.

🌟 AUTHOR 🌟

The VirusTotal CLI authors.

This manual page was written by Josenilson Ferreira da Silva nilsonfsilva@hotmail.com for the Debian project.

okay that's the whole thing, you're fully caught up bestie 🫶 this was vt-cli version 1.3.1, dated 2025-06-13 — now go forth and slay some threat intel, no cap 💖✨

📦 where this page comes from