Command-line interface

Install the vulnara CLI, sign in or use a service account, pick a default workspace, and run every Vulnara API operation from your terminal.

The vulnara command-line interface is a single binary that talks to the Vulnara GraphQL API. It gives you one command for each API operation, so you can list repositories, start scans and read findings from a terminal or a script. It prints results as JSON.

What it is for

Starting scans and reading results without opening the web app.
Scripting against Vulnara, with a service account instead of a person's login.
Pulling findings into other tools as JSON files.

How it works

Each command maps to one API operation, named in snake case: repositories, start_repository_scan, scan_findings. A command's flags are the fields of that operation's input, so start_repository_scan takes --repositoryId, --branch, --dockerScanToolId and so on. Run vulnara --help for the list, and vulnara <command> --help for a command's flags.

Before each command, the CLI finds an access token, picks the workspace, sends the request, and prints the result.

Besides the API commands, there are four of its own: login, set_default_tenant, completion and add_to_path.

What you can set

--tenant: run one command against this workspace instead of your default one. Works on every API command.
--output: write the raw JSON result to a file instead of printing it. Works on every API command.
--filters (or -f): on list commands, filter by field=value. Repeat it to add more filters.
--limit and --skip: on list commands, page through results.
--sort and --order: on list commands, sort by a field, ASC or DESC.
--search: on list commands, a free-text search.
VULNARA_TIMEOUT: how long a request may take, in seconds. The default is 300.
VULNARA_LOG_LEVEL and VULNARA_LOG_FORMAT: turn on diagnostic logs (debug, info, warn, error) as json or text. They are off by default.

Do it

Install
The CLI is distributed as release archives for Linux x86_64, macOS on Apple silicon and Intel, and Windows x86_64: vulnara-cli_Linux_x86_64.tar.gz, vulnara-cli_Darwin_arm64.tar.gz, vulnara-cli_Darwin_x86_64.tar.gz and vulnara-cli_Windows_x86_64.zip. Unpack the archive. The binary inside is called vulnara and needs no other setup.
To put it on your PATH, run it once from where you unpacked it:
sh
```
./vulnara add_to_path
```
This adds the binary's directory to ~/.bashrc, ~/.zshrc and ~/.bash_profile, and to ~/.config/fish/config.fish, but only to the files that already exist. Restart your shell afterwards.
Sign in
sh
```
vulnara login
```
Your browser opens the Vulnara sign-in page. Sign in within 3 minutes. The CLI receives the tokens on a local port between 10000 and 10010, and stores them. It renews them by itself when they expire.
Set a default workspace
sh
```
vulnara set_default_tenant --tenant my-workspace
```
Every command now runs against my-workspace unless you pass --tenant.

Run a command

vulnara repositories --limit 20
vulnara repositories --filters repositoryName=my-app
vulnara start_repository_scan --repositoryId <id> --dockerScanToolId <id> --branch main
vulnara scan_findings --filters scanResultId=<id> --output findings.json

The full list of commands and their flags is on the CLI reference.

Use a service account in scripts and CI

For a machine with no browser, use a service account. Write its name and token to ~/.config/vulnara/sa/service_account.json:

json

{ "username": "<service account name>", "password": "<token>" }

When this file is filled in, the CLI signs in with it on every run and needs no login. Set the workspace with set_default_tenant or --tenant as usual.

Shell completion

vulnara completion bash
vulnara completion fish

bash: adds a line to ~/.bashrc that loads completion, and prints the completion script.
fish: writes ~/.config/fish/completions/vulnara.fish.
zsh: vulnara completion zsh does nothing yet. Add . <(vulnara completion zsh) to ~/.zshrc yourself.
PowerShell: vulnara completion powershell prints the line to add to your profile instead of installing it.

Where the CLI keeps its state

Everything lives under ~/.config/vulnara/:

sa/service_account.json: the service account name and token, if you use one.
jwt/access_token and jwt/refresh_token: the tokens from login or from the service account.
tenant/default_tenant: the workspace set with set_default_tenant.

The CLI creates these files, empty, the first time it runs.

Good to know

File permissions: the token files and the service account file are created readable by every user on the machine. On a shared machine, restrict them yourself, for example with chmod 600.
No default workspace: if you have not set one and pass no --tenant, the CLI warns you and sends the request with no workspace. Set a default to avoid surprises.
Empty values are not sent: a flag set to false, 0 or an empty string is treated as not given. --limit 0 and --skip 0 have no effect.
Filters need an equals sign: --filters repositoryName without =value is rejected.
Command names with acronyms: check vulnara --help for the exact spelling of a command whose operation name contains an acronym.
Login needs a local browser: vulnara login only works where the browser can reach localhost on the same machine. If all ports from 10000 to 10010 are busy, or it times out, use a service account instead.
Two browser tabs: vulnara login may open the sign-in page twice. Complete it in either tab.
Logs and JSON: diagnostic logs go to stdout. Leave VULNARA_LOG_LEVEL unset when you pipe output into jq, or use --output.
Roles still apply: the CLI can do only what your role in the workspace allows. See Teams and roles.