VirusTotal CLI: Installation and First File Lookup

Why VirusTotal CLI Exists Beyond Web Lookup

VirusTotal CLI addresses the gap between manually using the VirusTotal web interface and interacting with its API from scripts or an interactive shell. Its documented command groups cover files, URLs, domains, IP addresses, searches, file downloads, LiveHunt YARA rules, and Retrohunt jobs. The intended user is someone who already understands VirusTotal objects and wants those operations exposed through the `vt` command rather than navigating the GUI.

That distinction matters because the CLI does not replace VirusTotal analysis. It uses the VirusTotal API underneath, so every lookup depends on a VirusTotal account, network access to the service, and an API key. A free key has a limited number of requests per minute and cannot access premium features such as searches and file downloads. Those operations therefore require the appropriate VirusTotal account rather than a local CLI configuration change.

The project also suits repeatable analyst workflows. Commands support named resource types and output formatting, while shell completion can expose commands available to the configured API account. That makes the tool more relevant to an investigation console or a terminal-based support environment than to a user who occasionally checks one hash through a browser.

The vt Command Path from API Key to Analysis Output

The repository is a Go command-line program built around `github.com/spf13/cobra`, `github.com/spf13/pflag`, and `github.com/spf13/viper`. The `Makefile` identifies the installable program as `github.com/VirusTotal/vt-cli/vt`, while the local build target writes an executable named `./build/vt`. The dependency on `github.com/VirusTotal/vt-go` connects the command layer to VirusTotal API operations.

At invocation time, the program needs an API key. The README documents three sources: the `--apikey` option, the `VTCLI_APIKEY` environment variable, and the configuration file at `~/.vt.toml`. Their precedence is explicit. `--apikey` wins, followed by `VTCLI_APIKEY`, with the saved configuration used last. This ordering allows a one-off override without requiring the stored key to be changed.

A command such as `vt file` sends the requested hash to VirusTotal and renders the returned file information. Adding `--format json` changes the machine-readable output rather than the underlying resource requested. Searches, downloads, LiveHunt operations, and Retrohunt commands use the same service-backed model, although premium access may be required. The repository also includes dedicated documentation under `doc/` and shell completion generation, but it does not document an offline analysis database or local replacement for VirusTotal's remote results.

Installing vt-cli and Creating the Initial Configuration

The README offers precompiled archives for Windows, Linux, and Mac OS X, plus source installation. There is a documentation inconsistency worth noticing before building: the README says Go 1.14.x or higher, while `go.mod` declares `go 1.22.0`. The module declaration is the more specific project requirement, so a Go 1.14 installation may not match the current module configuration.

For source installation, clone the repository and invoke the Makefile's `install` target. This uses `go install` and places the `vt` executable in the Go binary directory. The following export commands add that directory to `PATH` for the current shell.

$ git clone https://github.com/VirusTotal/vt-cli
$ cd vt-cli
$ make install

After installation, make the installed binary available through `GOBIN` on `PATH`. The README presents the Go workspace's `bin` directory as that location.

$ export GOBIN=`go env GOPATH`/bin
$ export PATH=$PATH:$GOBIN

The first configuration step runs `vt init`. It prompts for a VirusTotal API key and stores it in `~/.vt.toml`. This is preferable to placing a secret in shell history for repeated use, although the file's permissions are not discussed in the README.

$ vt init

If your network requires an HTTP proxy, the README documents `VTCLI_PROXY` and a `proxy` config entry in addition to `--proxy`. Its sample uses `http://myproxy.com:1234`.

$ vt --proxy http://myproxy.com:1234 <command>

Running the First vt File Lookup

A first use can be a lookup for a known SHA-256 hash. The README's example passes the hash directly to `vt file`, producing information associated with that file. No local file needs to be selected, and no scan engine is configured in the CLI.

$ vt file 8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85

For scripts or pipelines, the documented JSON format avoids depending on the human-readable table layout. The same resource is requested, but the output is selected with `--format json`.

$ vt file 8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85 --format json

This is a service lookup, not a claim that the hash was scanned locally. Network errors, authentication failures, rate limits, unavailable objects, or account restrictions can all affect what reaches the terminal, although the README does not document their exact error messages or retry behavior. The completion command is also API-dependent because VirusTotal determines which commands the account can access.

On Linux, the README shows completion being written into `/etc/bash_completion.d/vt`. That path requires suitable filesystem permission. Other documented variants write to Cygwin or Homebrew locations. The README advises restarting the shell after setup because completion may not appear in the current session.

$ vt completion bash > /etc/bash_completion.d/vt

Terminal UX, Proxy Boundaries, and Windows Output

VirusTotal CLI is designed around terminal output, which creates a practical Windows constraint. The README says the standard Windows console is slow when printing large amounts of text and recommends Cygwin for regular use. Cygwin also provides `bash-completion` support that the standard console lacks. This is a usability warning rather than a claim that the command cannot run in Windows.

The Homebrew formula and Winget manifest simplify installation on macOS and Windows, but the README explicitly says neither is maintained by VirusTotal. That distinction affects upgrade confidence. The Homebrew command is `brew install virustotal-cli`, while the documented Winget command is `winget install VirusTotal.vt-cli`. The source-built or downloaded `vt` binary is the direct project path; package managers add an external maintenance layer.

Proxy support is similarly service-dependent. `VTCLI_PROXY` and `proxy="http://myproxy.com:1234"` in the configuration file are documented, but the README does not describe authentication schemes for proxies or their behavior with downloads. It also does not document certificate customization, request concurrency, timeout configuration, or offline operation. Treat the proxy examples as configuration evidence, not a complete network policy reference.

VirusTotal CLI Versus Direct API and Local File Inspection

The real alternative is direct use of the VirusTotal API through a program such as a Go client or an HTTP script. Both approaches send the same indicator to VirusTotal and require an API key. The CLI adds command parsing, resource-specific subcommands, formatted terminal output, configuration loading, and shell completion. A custom script offers more control over request sequencing, structured processing, and application-specific error handling, but that logic must be written and maintained separately.

Another apparent use case is local inspection, but VirusTotal CLI is not a replacement for it. The repository describes retrieval of VirusTotal file information, analysis reports, downloads, and threat-intelligence queries. It does not describe a local static scanner, signature database, unpacking engine, or private analysis service. Sending a private file to the service is therefore outside what these commands establish. The README gives download support for files, yet access to downloads is identified as a premium feature.

The project is most useful when the analyst wants several remote VirusTotal capabilities under one `vt` interface. It is less suitable when low-level HTTP control, guaranteed offline processing, or custom automation is the primary requirement. The README also does not state whether interactive sessions retain history, whether output can be piped without terminal formatting, or whether there is a documented bulk mode.

Release Cadence, Go Dependencies, and Apache-2.0

The repository is not archived, and its last push was on 2026-07-07. Recent releases include 1.3.1 on 2026-05-19, 1.3.0 on 2026-02-17, and 1.2.0 on 2025-10-01. These facts indicate recent repository and release activity, although they do not establish the stability or support duration of every API and CLI feature.

The upgrade surface is larger than a self-contained executable with no modules. `go.mod` pins `github.com/VirusTotal/vt-go`, Cobra, Viper, the ANSI packages, download helpers, and other dependencies. Go module compatibility and the difference between binary releases and source builds should therefore be considered together. The README does not document a compatibility matrix, automatic CLI updates, a rollback procedure, or release notes for individual commands.

The repository uses the Apache-2.0 license. That identifier permits use and modification under the license's conditions, including preservation of applicable notices. This is a repository fact, not a conclusion about legal compliance. Organizations still need to review the actual `LICENSE` file, dependencies, service terms, confidentiality requirements, and policies for transmitting indicators to VirusTotal. The README does not promise that every command or returned artifact is covered solely by the repository license.

Editorial conclusion

VirusTotal CLI is appropriate for analysts who already use VirusTotal and want repeatable terminal access to its API. It is a poor fit for users needing premium features with a free key, developers requiring a local scanning engine, or teams that cannot send indicators to the VirusTotal service. Before adoption, verify account access, request limits, proxy requirements, output formats, and how secrets are handled by `VTCLI_APIKEY` or `~/.vt.toml`.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. VirusTotal/vt-cli on GitHub