VT-CLI(1)

NAME
vt-cli - command-line interface for the VirusTotal threat analysis platform

SYNOPSIS
vt-cli [OPTIONS] COMMAND [ARGS]

DESCRIPTION
vt-cli provides a command-line interface to the VirusTotal API v3, allowing security analysts and researchers to query and interact with VirusTotal's threat intelligence database directly from the terminal.

Files, URLs, IP addresses, and domains can be submitted for analysis or queried for existing reports. Results are output in YAML by default and can be exported in JSON or CSV format.

A VirusTotal API key is required. Free keys are available upon registration but 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.

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.

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.

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.

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.

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.

-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.