The world's fastest OpenAPI, AsyncAPI, Arazzo and JSON Schema linter.
An ultra-super-fast, lightweight OpenAPI, AsyncAPI, Arazzo and JSON Schema linter and quality checking tool inspired by Spectral.
It supports Spectral-style YAML and JSON rulesets. See Spectral migration for compatibility limits and built-in alternatives.
Install using the official homebrew tap
brew install --cask daveshanley/vacuum/vacuum
Install using npm
npm i -g @quobix/vacuum
Install using yarn
yarn global add @quobix/vacuum
Install using curl
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
For CI/CD environments
To avoid GitHub API rate limiting in automated environments, set a GitHub token:
# Using repository token (GitHub Actions)
GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
# Using personal access token
GITHUB_TOKEN=your_github_token curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
GitHub Actions example
- name: Install vacuum
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Increases rate limit from 60 to 5000 requests/hour
run: |
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
Note: The GitHub token prevents intermittent installation failures in CI/CD environments caused by API rate limiting.
No additional permissions are required, the token only accesses public repository information.
Install using Docker
The image is available at: https://hub.docker.com/r/dshanley/vacuum
docker pull dshanley/vacuum
Multi-platform support: Docker images are available for both linux/amd64 and linux/arm64 architectures, including native ARM64 support for Apple Silicon Macs.
To run, mount the current working dir to the container and use a relative path to your spec, like so
docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>
Alternatively, you can pull it from
GitHub packages.
To do that, replace dshanley/vacuum with ghcr.io/daveshanley/vacuum in the above commands.
Run with Go
If you have Go 1.27.3 or newer installed, you can use go run to build and run it:
go run github.com/daveshanley/vacuum@latest lint <your-openapi-spec.yaml>
Upgrade vacuum
If vacuum was installed with Homebrew, npm, or the shell installer, run:
vacuum upgrade
vacuum will detect the install path and use the matching upgrade mechanism when it can. Normal commands may also show an
update notice when a newer stable release is available. The passive check keeps only a small temporary cache in the OS temp
directory, refreshed at most every 12 hours. Use --no-update-check or VACUUM_NO_UPDATE_CHECK=true to skip that check.
Sponsors
If your company is using vacuum, please consider supporting this project,
like our very kind sponsors, past and present:
scalar
apideck
Come chat with us
Need help? Have a question? Want to share your work? Join our discord and
come say hi!
Timeout behavior
Resolved rule lookups no longer retry against unresolved documents after a timeout or query error.
This applies to plain linting and dashboard commands, reports, and library callers as well as --original comparisons.
lint and dashboard return exit code 2 when a lookup or rule execution times out.
Without --original, vacuum report records these failures as execution errors; its findings can be incomplete.
Spectral and HTML output retain their existing formats and can omit findings from failed rules.
A comparison with --original stops with exit code 2 if either lint run fails and does not produce a comparison report.
Library callers must check RuleSetExecutionResult.Errors, including RuleLookupError and RuleTimeoutError.
For large documents, increase --lookup-timeout (milliseconds, default 500) if a JSONPath lookup needs more time,
or --timeout (seconds, default 5) if the complete rule needs more time. The rule budget must also allow the lookup to finish.
A timeout is an incomplete check, not evidence that the document is clean.
Documentation
🔥 New in v0.36 🔥: 12 report output formats
Export lint results in 12 formats, including SARIF, JUnit, GitLab Code Quality, HTML and Markdown.
Use vacuum lint --format to choose the output, or write multiple reports from one lint run.
v0.34: Agent testing in vacuum
A new test command gives agents a way to test rules, check changes and verify repairs using vacuum's existing engine.
Define a YAML or JSON suite, run vacuum test suite.yaml, and get structured results with evidence of what each rule actually did.
Check expected findings, selector matches and function calls. Test before-and-after changes, verify autofix output,
and check that running a fix again makes no further change. A clean result is only useful if the rule actually ran.
v0.33: Arazzo workflow linting and a new or function
Arazzo 1.0 and 1.1 workflows are now a first-class document type in vacuum, alongside OpenAPI, AsyncAPI and JSON Schema.
Use vacuum lint workflows.yaml and vacuum will detect Arazzo automatically, with recommended rules for workflow structure,
references, parameters, expressions and linked source documents. Results work in the normal reports, dashboard and editor diagnostics.
The new or core function checks that at least one of two or more properties exists. Use
properties: [title, summary, description] to require one of those fields. A property counts as present even when its
value is null, false, 0 or an empty string.
This release also fixes AsyncAPI header, server and version checks, and improves result locations for YAML aliases and shared references.
v0.29: Lint AsyncAPI 3 documents in vacuum
AsyncAPI is now a first-class document type in vacuum, alongside OpenAPI and JSON Schema.
Use the normal lint command and vacuum will detect AsyncAPI 3 documents automatically.
v0.28: Lint JSON Schema documents in vacuum
A new schema command has been added that opens up vacuum to JSON Schema specific linting rules and checks!
With a whole new set of functions and rules, specifically for JSON Schema documents.
Try it out on your own JSON Schema docs! with vacuum schema
v0.27: Generate OpenAPI Documentation in vacuum
A new docs command will generate the best OpenAPI Documentation you ever saw! Now vacuum has
integrated with the printing press, it means
generating documentation with built-in linting results is available right inside vacuum.
Try it out! instead of the lint command try the docs command instead.
v0.25: Generate Open Collections from OpenAPI files
A new open-collection command will generate an Open Collection Workflow folder
(or bundled file)
Open Collection is a new standard for defining and sharing API collections. vacuum supports it natively.
Read More
v0.24: TURBO MODE
A huge tune up of hundreds of systems across the stack has resulted in significant speed boosts and improved memory performance.
| Spec | Size | v0.23 | Turbo | Speedup |
|---|
| petstore.yaml | 21KB | 0.03s | 0.02s | 33% |
| mistral.yaml | 292KB | 0.17s | 0.10s | 41% |
| neon.yaml | 370KB | 0.21s | 0.08s | 62% |
| ld.yaml | 1.9MB | 0.93s | 0.31s | 67% |
| plaid.yml | 2.9MB | 1.39s | 0.53s | 62% |
| stripe.yaml | 6.1MB | 3.11s | 0.85s | 73% |
The bigger the spec, the faster vacuum runs!
New -T flag will enable turbo mode. Go ultra-fast!
v0.23: OpenAPI Overlay Support
Ever needed to tweak an OpenAPI spec for different environments without maintaining multiple copies?
Maybe swap out server URLs between dev, staging, and production? Or perhaps strip out internal endpoints before publishing the API docs?
OpenAPI Overlays are the answer. They let us make non-destructive modifications to specs using JSONPath expressions to
target exactly what we want to change. vacuum now supports a new apply-overlay command.
apply-overlay can also build a fail-closed publication document after applying
the standard Overlay actions:
vacuum apply-overlay internal.yaml public.overlay.yaml public.yaml \
--include-tag public \
--tag-match any \
--prune-unused
The overlay file is optional when a filter or --prune-unused is active:
vacuum apply-overlay internal.yaml public.json --exclude-tag internal --prune-unused
vacuum apply-overlay internal.yaml selected.yaml --include-operation-id listPets
Tags and operation IDs are exact and case-sensitive. All four filter flags
(--include-tag, --exclude-tag, --include-operation-id, and
--exclude-operation-id) can be repeated. --tag-match any matches at least
one tag; all requires every tag in each include/exclude list. Each active
inclusion filter must match, and exclusions take precedence. Operations with
no tags or IDs survive exclusion-only filtering. Filtering runs after Overlay
actions and before pruning. --prune-unused removes unreachable components
and unused tag definitions, retaining parents of used OpenAPI 3.2 tags.
These opt-in transforms require a bundled, self-contained OpenAPI document.
YAML merge keys are expanded. Aliases are expanded when filtering or when a removed tag owns an anchor. Retained mapping
order, comments, and scalar styles are preserved. Pruning rejects schema
$id scopes that cannot be resolved safely. Link Objects targeting filtered
operations are retained and reported as warnings. Document output remains
pure on stdout; warnings are written to stderr. The warning summary uses the apply-overlay produced prefix to
cover both Overlay actions and publication transforms.
A .json, .yaml, or .yml output extension selects the output format.
Otherwise the input format is retained, including on stdout.
An inferred output path containing an Overlay document is rejected to prevent accidental overwrites.
Tag pruning retains x-tagGroups entries and x-traitTag: true narrative tags.
Library callers opt into tag pruning with Options.PruneUnusedTags;
Options.PruneUnused and PruneUnusedComponents continue to prune components only.
v0.22: Async Functions / Promises, Fetch & Batch mode in Custom JS Functions
Do you want to call remote APIs in your vacuum javascript functions? What about async processing or the ability to use Promises?
vacuum now has its own event loop and will happily support async and await. Combined with a full implementation of Fetch.
Also added Batch Mode. This allows custom functions to receive the entire list of nodes, instead of firing the function
for each result, so you can send all your data off to an API or an LLM, and have the ability parse and process everything at once
vs individually.
Bundle AsyncAPI 3
vacuum bundle detects AsyncAPI 3 documents and supports inline and composed output:
vacuum bundle events.asyncapi.yaml bundled.yaml
vacuum bundle events.asyncapi.yaml bundled.json --composed --delimiter __
cat events.asyncapi.yaml | vacuum bundle --stdin --stdout --base ./specs --format json
External objects are inlined by default. Shared schemas are emitted once, with
local references for later uses. Composed mode stores external objects in AsyncAPI
component sections. Both modes preserve the local references required by
operations, messages, channels, and servers. Input-file references resolve from
the input directory unless --base is supplied. Use --remote=false to disable
remote loading; --ext-refs opts into resolving references inside extensions.
Unresolved or ambiguous references return an error without writing an incomplete
bundle. Schema resource IDs are resolved before relocation. Non-JSON schema
content is preserved; language-specific imports and dynamic JSON Schema references
are not bundled.
Multi-file editor diagnostics
For a specification split across files, configure your editor to run
vacuum language-server ./openapi.yaml. The optional root can also be an HTTP(S)
URL. The server lints the root specification with its references and sends each
open document its own diagnostics. Unsaved edits in open files take precedence
over their stored content. Without a root argument, each document is linted
independently.
See all the documentation at https://quobix.com/vacuum
vacuum can suck all the lint of a 5mb API description in milliseconds.
Designed to reliably lint API descriptions, very, very quickly. Including very large ones. Spectral can be quite slow
when used as an API and does not scale for enterprise applications.
vacuum will tell you what is wrong with your spec, why, where, and how to fix it.
vacuum will work at scale and is designed as a CLI (with a web or console UI) and a library to be consumed in other applications.
Dashboard
vacuum comes with an interactive dashboard (vacuum dashboard <your-openapi-spec.yaml>) allowing you to explore
rules and violations in a console, without having to scroll through thousands of results.
To read about the dashboard, see the dashboard command docs.
HTML Report
vacuum can generate an easy to navigate and understand HTML report. Like the dashboard
you can explore broken rules and violations, but in your browser.
No external dependencies, the HTML report will run completely offline.
Supports OpenAPI Version 2, OpenAPI Version 3+, AsyncAPI 3, and JSON Schema documents
You can use either YAML or JSON, vacuum supports both formats.
Using vacuum with pre-commit
vacuum can be used with pre-commit.
To do that, add to your .pre-commit-config.yaml:
repos:
- repo: https://github.com/daveshanley/vacuum
rev: # a tag or a commit hash from this repo, see https://github.com/daveshanley/vacuum/releases
hooks:
- id: vacuum
See the hook definition here for details on what options the hook uses and what files it checks by default.
If no filenames or more than one filename in your repository matches the default files pattern in the hook definition,
the pattern needs to be overridden in your config so that it matches exactly one filename to lint at a time.
To lint multiple files, specify the hook multiple times with the appropriate overrides.
Build an interactive HTML report
vacuum html-report is included in official release binaries. If you install via go install github.com/daveshanley/vacuum@<version>, the command is compiled without the HTML report UI bundles. To enable it from source, run ./scripts/build-ui-assets.sh and build with -tags html_report_ui.
./vacuum html-report <your-openapi-spec.yaml | vacuum-report.json.gz> <report-name.html>
You can replace report-name.html with your own choice of filename. Open the report
in your favorite browser and explore the results.
See full linting report
./vacuum lint -d <your-openapi-spec.yaml>
Lint multiple files at once
./vacuum lint -d <spec1.yaml> <spec2.yaml> <spec3.yaml>
Lint multiple files using a glob pattern
./vacuum lint -d some/path/**/*.yaml
See full linting report with inline code snippets
./vacuum lint -d -s <your-openapi-spec.yaml>
See just the linting errors
./vacuum lint -d -e <your-openapi-spec.yaml>
See just a specific category of report
./vacuum lint -d -c schemas <your-openapi-spec.yaml>
The options here are:
examplesoperationsinformationdescriptionsschemassecuritytagsvalidationowasp
Generate a Spectral compatible report
If you're already using Spectral JSON reports, and you want to use vacuum instead, use the spectral-report command
./vacuum spectral-report <your-openapi-spec.yaml> <report-output-name.json>
The report file name is optional. The default report output name is vacuum-spectral-report.json
Generate a vacuum report
vacuum reports are complete snapshots in time of a linting report for a specification. These reports can be 'replayed'
back through vacuum. Use the dashboard or the html-report commands to 'replay' the report and explore the results
as they were when the report was generated.
./vacuum report -c <your-openapi-spec.yaml> <report-prefix>
The default name of the report will be vacuum-report-MM-DD-YY-HH_MM_SS.json. You can change the prefix by supplying
it as the second argument to the report command.
Ideally, you should compress the report using -c. This shrinks down the size significantly. vacuum automatically
recognizes a compressed report file and will deal with it automatically when reading.
When using compression, the file name will be vacuum-report-MM-DD-YY-HH_MM_SS.json.gz. vacuum uses gzip internally.
Selecting property names in custom rules
Use quoted bracket notation for JSONPath property names with special characters, for example ['$ref'] and ['application/json']. A single leading backtick also escapes a member name in dot notation or an unquoted bracket selector:
$.paths.*.*.requestBody.content.`application/json.schema.`$ref
There is no closing backtick; a trailing backtick becomes part of the property name. Use quoted bracket notation for names that contain path separators or whitespace, and for properties inside filters. Quoted names keep literal backticks unchanged.
To inspect a $ref property itself, set resolved: false. With resolved: true, rules inspect the referenced schema after resolution.
rules:
no-request-body-refs:
description: Request body schemas must be inline.
given: "$.paths.*.*.requestBody.content['application/json'].schema['$ref']"
resolved: false
severity: warn
then:
function: falsy
Ignoring specific linting errors
You can ignore specific linting errors by providing an --ignore-file argument to commands that run or replay lint results, including lint, report, spectral-report, html-report, dashboard, docs, schema, and language-server.
./vacuum lint --ignore-file <path-to-ignore-file.yaml> -d <your-openapi-spec.yaml>
./vacuum report --ignore-file <path-to-ignore-file.yaml> -c <your-openapi-spec.yaml> <report-prefix>
Repeat --ignore-file to combine waivers from multiple files. Paths for the same rule are appended; an unreadable or invalid file stops the command.
./vacuum lint --ignore-file pets-ignore.yaml --ignore-file stores-ignore.yaml api.yaml
In vacuum.conf.yaml, ignore-file accepts either one path or a YAML list of paths. A scalar value, including VACUUM_IGNORE_FILE, is always one path; commas are part of the filename.
Language-server editor settings accept ignoreFiles: ["one.yaml", "two.yaml"]; the legacy ignoreFile string still works. An empty ignoreFiles list clears waivers. Explicit CLI ignore files override disk config; editor initialization and workspace settings can override the CLI defaults.
The ignore-file should point to a .yaml file that contains exact result paths or JSONPath expressions to be ignored by vacuum. The structure of the YAML file is as follows:
<rule-id-1>:
- <json_path_to_error_or_warning_1>
- <json_path_to_error_or_warning_2>
<rule-id-2>:
- <json_path_to_error_or_warning_1>
- <json_path_to_error_or_warning_2>
...
Ignoring errors is useful for when you want to implement new rules to existing production APIs. In some cases,
correcting the lint errors would result in a breaking change. Having a way to ignore these errors allows you to implement
the new rules for new APIs while maintaining backwards compatibility for existing ones.
Try out the dashboard
This is an early, but working console UI for vacuum. The code isn't great, it needs a lot of clean up, but
if you're interested in seeing how things are progressing, it's available.
./vacuum dashboard <your-openapi-spec.yaml | vacuum-report.json.gz>
OWASP hard mode
Run vacuum lint --hard-mode api.yaml to enable all built-in OpenAPI rules,
including the OWASP rules. Hard mode checks:
- OAuth password
and implicit flows.
- Authentication endpoint URLs
and server URLs for HTTPS, including overrides and server variables.
- Request objects for unrestricted fields and maps for property-count limits.
- Write operations for authenticated security requirements, without anonymous alternatives.
- Declared JWTs for an RFC8725 reference in their description, as a warning.
Changes for existing users: strict write security now reports an error,
previously informational. A requirement such as security: [{auth: []}, {}] can
now fail a build. Also, x-lint-ignore applies to the entire subtree beneath its
location for every ruleset, rather than only the node and its immediate children.
See the OWASP guide for rule details
and severity overrides, and ignoring violations
for scoped exceptions.
Spectral migration
vacuum loads YAML, JSON, and local JavaScript rulesets. Resolve each relative extends path from the
file that contains it, including on Windows. Keep sibling rulesets relative:
extends:
- ./ruleset.bank.yml
- ./ruleset.nlgov.yml
- [vacuum:owasp, all]
Use [vacuum:owasp, all] for vacuum's built-in OWASP checks instead of importing
@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs. The native rules use vacuum's
rule names and behavior; they do not execute the Spectral package.
For JavaScript rulesets, export an object from a local .js, .mjs, or .cjs file:
vacuum lint api.yaml -r rules.mjs
Functions, static imports, Promises, and callable formats run in an isolated runtime
for each document. See JavaScript rulesets
for supported imports, context, and migration limits.
Arazzo 1.0 and 1.1 workflows use vacuum lint workflows.yaml and the normal
report commands. spectral:arazzo selects Vacuum's native recommended rules.
See Arazzo linting for source lookup, rule IDs, incomplete checks
and migration differences.
--functions takes a directory containing custom function files:
vacuum lint api.yaml --ruleset rules/main.yaml --functions ./functions
JavaScript ruleset functions do not need this directory. Omitting the directory after --functions reports an
input error and exits with code 2. In the editor, vacuum checks recognized ruleset
buffers against its ruleset schema instead of reporting an unsupported API type.
Supply your own Spectral compatible ruleset
If you're already using Spectral and you have your own custom ruleset,
then you can use it with vacuum!
The lint, dashboard, docs, html-report, report, and spectral-report commands all accept a -r or --ruleset flag, defining the path to your ruleset file.
Here are some examples you can try
All rules turned off
./vacuum lint -r rulesets/examples/norules-ruleset.yaml <your-openapi-spec.yaml>
Only recommended rules
./vacuum lint -r rulesets/examples/recommended-ruleset.yaml <your-openapi-spec.yaml>
Enable specific rules only
./vacuum lint -r rulesets/examples/specific-ruleset.yaml <your-openapi-spec.yaml>
Custom rules
./vacuum lint -r rulesets/examples/custom-ruleset.yaml <your-openapi-spec.yaml>
All rules, all of them!
./vacuum lint -r rulesets/examples/all-ruleset.yaml <your-openapi-spec.yaml>
Reference resolution in rules
vacuum has two resolved-execution controls:
- Per rule:
resolved
- Per run:
--resolve-all-refs or motor.ExecutionOptions{ResolveAllRefs: true}
In YAML/JSON rulesets, resolved defaults to true. In that mode, given, matched nodes, Index, and SpecInfo come from the dereferenced document, but context.Document stays unresolved for compatibility.
Set resolved: false when a rule needs the raw document, for example to inspect $ref directly. If you build model.Rule values in Go, set Resolved explicitly.
rules:
response-has-content:
given: "$.paths[*][*].responses['404']"
resolved: false
then:
field: content
function: defined
--resolve-all-refs forces every rule into resolved execution, overrides resolved: false, and also supplies resolved context.Document to rule functions.
Use --nested-refs-doc-context or motor.ExecutionOptions{NestedRefsDocContext: true} for split specs where an external file contains another relative $ref. That makes nested relative refs resolve from the referenced document instead of the root document. It only affects resolved execution, including runs forced by --resolve-all-refs.
Configuration
File
You can configure vacuum using a configuration file named vacuum.conf.yaml
By default, vacuum searches for this file in the following locations:
- Working directory
$XDG_CONFIG_HOME, when set${HOME}/.config, when $XDG_CONFIG_HOME is not set
You can also specify a path to a file using the --config flag
Global flags are configured as top level nodes
time: true
base: 'http://example.com'
...
Command specific flags are configured under a node with the commands name
...
lint:
silent: true
...
Environment variables
You can configure global and command-local flags with VACUUM_<FLAG>
environment variables. Use uppercase flag names and replace - with _.
Explicit command-line flags take precedence over environment variables;
environment variables take precedence over configuration files.
Collection flags accept comma-separated values. For example,
VACUUM_INCLUDE_TAG='public,partner' sets the included tags for
apply-overlay.
Auto-fixing rule violations
If you have a rule that doesn't need a human to look at it, and the change can be reliably automated you can configure an AutoFixFunction on the rule. When you then run the lint command you can pass the --fix flag and the violation will be automatically fixed.
Set up
- Define a rule that has an
autoFixFunction, e.g.:
rules:
use-compatible-extensions:
autoFixFunction: useExtensibleEnum
description: Prefer compatible extensions
id: use-compatible-extensions
given: "$.components.schemas[[email protected]]"
severity: warn
message: Use x-extensible-enum instead of enum for better compatibility
then:
field: enum
function: falsy
This rule flags any usage of enum and recommends they are updated to x-extensible-enum.
A simple change which can be easily auto fixed!
- Create a function which performs the auto-fix.
func useExtensibleEnum(
node *yaml.Node,
document *yaml.Node,
context *model.RuleFunctionContext,
) (*yaml.Node, error) {
if node.Kind != yaml.MappingNode {
return node, nil
}
for i := 0; i < len(node.Content); i += 2 {
if i+1 >= len(node.Content) {
break
}
keyNode := node.Content[i]
if keyNode.Value == "enum" {
keyNode.Value = "x-extensible-enum"
return node, nil
}
}
return node, nil
}
[!NOTE]
The auto fix function must satisfy the AutoFixFunction type.
It should take in the *yaml.Node of the violation, the root *yaml.Node of the document and the RuleFunctionContext.
It should return the fixed *yaml.Node and an error.
- Configure your
RuleSetExecution to use the auto fix function.
func Lint(rulesFile string, specFile string) error {
rules, err := rulesets.LoadLocalRuleSet(ctx, rulesFile)
if err != nil {
return fmt.Errorf("error loading ruleset: %w", err)
}
rs := rulesets.BuildDefaultRuleSetsWithLogger(slog.Logger).
GenerateRuleSetFromSuppliedRuleSet(rules)
// NOTE: only showing the fields on the RuleSetExecution relevant to auto-fixing.
results := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
AutoFixFunctions: map[string]model.AutoFixFunction{
"useExtensibleEnum": useExtensibleEnum,
},
ApplyAutoFixes: true,
RuleSet: rs,
})
// Write back to file if fixes were applied
if len(lintResults.FixedResults) > 0 && autoFix {
fileInfo, _ := os.Stat(specFile)
err = os.WriteFile(specFile, result.ModifiedSpec, fileInfo.Mode())
if err != nil {
return fmt.Errorf("failed to write file %s: %w", c.file, err)
}
}
return nil
}
When the auto fix function runs, if it returns an error the fix will not be applied, the error will be logged, and the violation will be reported in the standard results.
If the auto fix function succeeds the yaml node flagged by the violation will be replaced with the transformed version returned by the auto fix function.
[!TIP]
When using vacuum as a library You can access the fixed yaml content in the RuleSetExecutionResult.ModifiedSpec, and choose where to write the file.
When using vacuum as a cli, the --fix flag will overwrite the spec file in place, and --fix-file flag lets you specify an alternative file to write the content to, if you want to compare the outputs.
Usage
Logo gopher is modified, originally from egonelbre
