Working in a terminal is an essential and every day part of any software or DevOps engineer’s life. A terminal is perhaps the most common interface most of us use.
Terminal UIs are becoming more common these days, which is awesome.
Using a browser based app is cool, but there is something really cool about a console UI. That’s why
vacuum comes with a custom terminal UI for reviewing a linting run. I call it the dashboard
Run the dashboard against an OpenAPI spec
If you’re running docker, make sure you’re using the -it flag.
docker run --rm -v $PWD:/work:ro -it dshanley/vacuum dashboard sample.yaml
Run the dashboard command and pass in your OpenAPI spec, or
vacuum Report.
Make sure your terminal window is sized to at least 1024x768. Smaller sizes work, but the layout is best at 1024x768 or larger.
Navigating the Dashboard
Everything is keyboard driven (mouse wheel scrolling is also supported).
| Action | Keys | Action Result |
|---|---|---|
| Navigate rows | ↑↓ / j,k | Move up/down through violations |
| Page navigation | PgUp/PgDn | Page up/down through violations |
| Jump to top/bottom | g/G | Go to first/last violation |
| Toggle details view | Enter | Show/hide split view with violation details |
| Expand code view | x | Open full-screen code view modal |
| Open documentation | d | Show rule documentation modal |
| Filter by severity | Tab | Cycle through: All → Errors → Warnings → Info |
| Filter by category | c | Cycle through available categories |
| Filter by rule | r | Cycle through available rules |
| Toggle path column | p | Show/hide the path column |
| Clear filters/Close | Esc | Close modals/views or clear filters |
| Quit | q, Ctrl-C | Exit the dashboard |
Mouse Support
- Mouse wheel scrolling: Scroll through violations or within open modals
- Responsive: All views adapt to terminal resize
File Watching
The dashboard supports automatic file watching to re-lint specifications when they change. use the -W or --watch
flags to automatically updated the results.
Replaying a report
The dashboard can replay a vacuum report. This means the dashboard will load in all the results as they were captured Even if the current specification is different to what it was when the report was captured.
Simply replace the <my-openapi-spec.yaml> with the report file, which will look something like my-openapi-spec-report-07-04-22-12-30-21.json.gz. vacuum will auto-detect the report file.
Global Flags
dashboard supports the following global flags
| Short | Full | Input | Description |
|---|---|---|---|
| -r | –ruleset | string |
Use an existing ruleset file for linting |
| -f | –functions | string |
Path to custom function plugins |
| -p | –base | string |
Base URL or Base working directory to use for relative references |
| -u | –remote | bool |
Load remote references automatically if possible (default is true) |
| -k | –skip-check | bool |
Skip checking for a valid OpenAPI document, useful for linting fragments or non-OpenAPI documents |
| -g | –timeout | int |
How long (in seconds to wait) for a rule before it times out (default is 5 seconds) |
| -z | –hard-mode | bool |
Enable every single built-in rule (including OWASP). Only for adventurers and brave souls. |
| -W | –watch | bool |
Watch for file changes and automatically re-lint the specification |
| –ext-refs | bool |
Allow $ref pointers inside extension objects (x-) to be looked up |
|
| –cert-file | string |
Path to client certificate file for HTTPS requests that require custom certificates | |
| –key-file | string |
Path to client private key file for HTTPS requests that require custom certificates | |
| –ca-file | string |
Path to CA certificate file for HTTPS requests that require custom certificates | |
| –insecure | bool |
Skip TLS certificate verification (insecure) | |
| –allow-private-networks | bool |
Allow fetch() to access private/local networks (localhost, 10.x, 192.168.x) | |
| –allow-http | bool |
Allow fetch() to use HTTP (non-HTTPS) URLs in custom JavaScript functions | |
| –fetch-timeout | int |
Timeout for fetch() requests in seconds (default 30) | |
| –lookup-timeout | int |
Node lookup timeout value value in ms (default 500ms). | |
| –original | string |
Path to original/old spec file for inline comparison (filters results to changed areas) | |
| –changes | string |
Path to change report JSON file for filtering results to changed areas only | |
| –changes-summary | bool |
Show summary of what was filtered by --changes or --original |
|
| –breaking-config | string |
Path to breaking rules config file (default: ./changes-rules.yaml) |
|
| –warn-on-changes | bool |
Inject warning violations for each detected API change | |
| –error-on-breaking | bool |
Inject error violations for each breaking change |
Change Detection
The dashboard supports change detection to filter results to changed areas only:
When used with --error-on-breaking or --warn-on-changes, the dashboard will display
violations for detected API changes alongside regular linting results.
For comprehensive documentation on change detection features, see the Change Detection guide.
Watch Mode
The --watch or -W flag enables automatic file monitoring. When enabled, the dashboard will:
- Monitor file changes: Automatically detect when the specification file is modified
- Auto-relint: Re-run linting rules when changes are detected
- Preserve state: Maintain your current position and filters during updates
- Visual feedback: Show processing indicator (green ●) during re-linting
- Error handling: Display error messages if the updated spec becomes invalid
Example usage:
vacuum dashboard my-spec.yaml --watch
# or
vacuum dashboard my-spec.yaml -W
The dashboard will show a colored indicator in the status bar:
- Green ●: Currently processing file changes
- Red ●: Error occurred during re-linting