Console mode¶

The default mode of visao is one-shot console analysis. You pass a set of source files or a compile_commands.json. The analyzer prints findings to the terminal, then the process exits. This page covers the most-used flags and the shape of the output. For an exhaustive flag inventory see CLI reference.

Basic invocation¶

There are three orthogonal pieces of information the analyzer wants to know up front:

Target language. This tells the analyzer what to expect inside the files. Visao reads the extension of each file, so most runs need no option here. Refer to Languages.
```
visao --language go ...
visao --language cpp ...
visao --language python ...
```
Files. On Linux/macOS, pass them as positional arguments. On Windows, prefix the file list with -- to disambiguate from options:
```
# Unix
visao --language c main.c shell.c app/logic.c

# Windows
visao --language c -- main.c shell.c app\logic.c
```
A compile_commands.json works as the single positional argument; the analyzer routes each entry through the toolchain inferred from the compile command:
```
visao compile_commands.json
```
Header search paths. Regular includes (#include "...") come from -I; system includes (#include <...>) from --isystem:
```
visao --language c -I include --isystem /opt/sdk/include -- main.c
```

Output structure¶

On a TTY with colours enabled the output of visao is split into visual layers, from quietest to loudest:

Engine chatter (Using toolchain clang (clang), Parsing 1 / 3..., Solving …, Analysis completed) is rendered in dim ANSI. This is per-stage progress emitted by the analysis pipeline; it is useful for diagnosing slow or hung runs but typically not what you came for.
Reports are the findings. Each defect gets one block, with the file:line:col: error: <message> header followed by an indented source excerpt. The header location is underlined cyan, the error: badge is bold red, the message is bold, the source excerpt is dim.
Suspicious places, when --suspicious was asked for, follow the findings as their own section: one block per suspicion carrying its category, its confidence and the lines of code it is about, then a count per category. They are not findings and never affect the exit code. Refer to Suspicious places.
Final status is a single line, for example:
```
✓ Finished successfully · 316 ms
```
or:
```
✗ Failed to parse some files · 1.24 s
```
Green check / red cross, the literal status phrase, dim duration. The phrase stays verbatim, because external test tooling (OpenVEF, see Notes for test use) regex-matches it.

Pass --color always to force colours on a non-TTY (for example when piping to less -R), or --no-color / --color never to get plain ASCII. The standard NO_COLOR=1 environment variable is also honoured.

Where a rule is explained¶

Each finding belongs to a rule, and each rule carries an identifier such as arithm/division/zero. The catalogue at https://defectdb.org holds one page for each identifier. The page states what the rule looks for, why the code matters, and how to correct it. The address of a page is the host name and the identifier:

https://defectdb.org/arithm/division/zero

The machine formats carry both. SARIF puts the identifier in ruleId and the address in helpUri. The JSON report uses the same two names. The GitLab report puts the address in its links array, beside the link to the CWE entry.

Severity, locale, language standard¶

--severity {Paranoid,Low,Medium,High}: Filter out findings below the given level. Defaults to Low: everything except paranoid hints surfaces.
--locale {en-US,ru-RU}: Language of the defect messages.
--std <name>: Pin the C/C++ language standard for the analyzer (c99, c11, c17, gnu++17, …). When omitted, Visao adopts the standard the toolchain probe reported.

Selecting jobs¶

The analyzer can run several kinds of jobs in one invocation. Each job is on by default. A request for another job turns the defaults off. Pass --defects to run the defect detector next to the other jobs.

--defects / --disable-defects: The main defect detector. Enabled by default.
--dependency: Produce a module/zone dependency graph. Combine with --dep-graph-out <file.dot> and/or --dep-graph-out-png <file.png>.
--identify: Identify the language of each input file without running deeper analysis. Useful when the language is unknown ahead of time.

Verbosity and tracing¶

-v / --verbose <level> adjusts how much engine chatter is emitted. Levels: critical, error, info (default), debug.

Common examples¶

Run all defaults against a small project:

visao --language c -I include src/*.c

Use a compile DB and silence colours:

visao --no-color compile_commands.json

Cross-compile target probing. Point at a non-default GCC:

visao --compiler-path "gcc:/opt/arm-none-eabi/bin/arm-none-eabi-gcc" \
      --cpu arm --os linux --language c \
      -I include -- main.c

Force an update of the toolchain cache before analysis (typical first run on a CI agent):

visao --update-toolchains
visao --language c -- main.c

Run only the dependency analyser and emit a graph:

visao --dependency \
      --dep-graph-out out/deps.dot \
      --dep-graph-out-png out/deps.png \
      --language c -- src/*.c

Notes for test use¶

When invoked from OpenVEF or any other use that scrapes stdout, set VISAO_DISABLE_COLORS=y or NO_COLOR=1 (or pass --no-color). The output then contains no ANSI escape sequences. The canonical markers match the regexes that such tooling uses: file:line:col: error: <msg>, Finished successfully and Failed to parse some files.

The exit code is always 0; pass/fail is communicated through output content.