CLI Reference: nightvision openapi extract

nightvision openapi extract analyzes one or more source directories and writes a single OpenAPI document. The analysis runs locally and source code is not uploaded. The generated document is uploaded to NightVision, and to the target you select, unless you use --no-upload. If you use --dump-code, source snippets are embedded in that document and are included in the upload.

nightvision openapi extract [path/to/code ...] [flags]

nightvision openapi requires CLI 0.18.0 or later. On an earlier release, use nightvision swagger, which later releases also accept. --no-target requires CLI 0.19.0 or later; on an earlier release, use --no-upload in its place.

The CLI detects project roots and languages automatically. Use --lang only when you need to restrict a run to one language.

Common workflows

Try Source Intelligence before you create a target, generating openapi-spec.yml locally:

nightvision openapi extract . --no-target

Choose a filename and JSON output:

nightvision openapi extract . --no-target --file-format json --output api.json

Generate a specification and upload it to an existing API target:

nightvision openapi extract . --target my-api

Scan several services or shared-library directories into one specification:

nightvision openapi extract services/users services/billing shared/models \
  --no-target --output platform-api.yml

Only combine paths that belong in the same OpenAPI document. If separate applications declare the same paths, later discoveries can replace earlier ones.

Selecting the source

Flag	Purpose
--lang, -l	Restrict analysis to csharp, go, java, js, php, python, or ruby. Omit it for automatic detection.
--exclude	Exclude matching files or directories. Supply a comma-separated list or repeat the flag.
--no-default-excludes	Disable built-in exclusions such as dependency, build, migration, and test directories.
--root-path	Set the base for leading-slash exclude patterns and relative x-source values. By default, the common parent of the input paths is used.
--config, -c	Select the nv.config file. By default, each language group uses the file in its first detected scan directory.

Configuration and exclusions

Python analysis excludes common environment and dependency directories by default, including venv, env, site-packages, lib, dist, build, migrations, and tests. It also excludes files named test_*.py or *_test.py. A directory named test is not excluded automatically. Use --no-default-excludes when a route really is declared in excluded code, then use --exclude to keep the scan focused.

Controlling the output

Flag	Purpose
--output, -o	Set the output path. The default is openapi-spec.yml.
--file-format	Write yml (the default) or json. The CLI changes the output extension to match.
--version, -v	Set info.version in the generated OpenAPI document. The default is 0.1.
--extend, -e	Merge discovered routes into an existing OpenAPI document.
--dump-code, -d	Include source snippets for discovered routes in the generated document.
--diagnostics	Add the x-language-diagnostics summary to the OpenAPI document. This is separate from the diagnostics file written beside every result.
--break	Treat OpenAPI validation errors as fatal.

Every operation includes x-source: <file>~~<line>, which connects the route to its source location. Depending on the framework and code path, an operation may also include detected security requirements, x-roles, x-unsound, and x-nv-dast-sinks. See the Framework Support Index for the generated metadata and its limits.

Uploading to NightVision

By default, the command expects an API target and uploads the completed specification. Select it by name or UUID, or run without one:

Flag	Purpose
--target, -t	Select an existing target by name.
--target-id, -T	Select an existing target by UUID.
--project, -p	Disambiguate the target with a project name.
--project-id, -P	Disambiguate the target with a project UUID.
--no-target	Run without a target, to try Source Intelligence before you create one. The specification is still uploaded to NightVision. Requires CLI 0.19.0 or later.
--no-upload	Generate files locally without uploading them.

Use --no-target to evaluate Source Intelligence or to generate a specification you will review before attaching it to a target. A run that names no target fails and suggests --no-target. Without a target, the document carries a default title and server in place of the target’s name and URL. --no-target cannot be combined with --target or --target-id.

A run that exits with an error, including one that loses an entire language phase, is never uploaded over the target’s current specification. A recovered framework or handler failure is reported as a warning and does not fail the run, so inspect the diagnostics file when those warnings appear; the document may be missing routes or operation details.

Files produced by a run

For --output openapi-spec.yml, a successful run writes:

• openapi-spec.yml: the generated OpenAPI document.
• openapi-spec.diagnostics.json: a machine-readable record of the run.

The diagnostics file is written for every run that returns analysis results, including a run that discovers no routes. It records the CLI and API Excavator versions, redacted invocation, effective arguments, detected project roots, each root’s contribution, unresolved imports and calls, known analysis losses, and recovered failures. It is replaced on the next run so it always describes the adjacent result. A failure before any language produces a result, such as an invalid argument or failed login, cannot write this file.

If one language or project fails while others succeed, the CLI exits with an error and writes the usable portion to openapi-spec.partial.yml. It leaves openapi-spec.yml unchanged and does not upload the partial result. If no routes are discovered, the CLI exits with an error, writes the diagnostics file, and does not write an OpenAPI document.

The separate --diagnostics flag embeds only a language/framework summary in the OpenAPI document as x-language-diagnostics; it does not control the diagnostics file.

Diagnosing missing or incomplete routes

Start with openapi-spec.diagnostics.json:

1. Check projects to confirm that the intended project roots and languages were detected.
2. Check each project’s contribution for the interpreted file, entry point, and path counts. A testShaped root contains only test-shaped code.
3. Check excavator.containment. A recovered framework or handler failure means that part of the result is incomplete; a recovered language phase also makes the command fail.
4. Check unresolvedFrameworkImports and inTreeResolutionFailures for imports the analyzer could not resolve.
5. Check losses for discoveries the analyzer knowingly dropped.

Use these controls when a deeper support trace is needed:

Flag	Purpose
--log-level	Set extraction logging to debug, info, warn, or error.
--max-concurrency	Limit files parsed concurrently. 0 uses one worker per CPU. Lower values reduce peak memory at the cost of speed.
--dump-memory	Write the analyzer’s internal memory model for post-mortem debugging. On a multi-language run, only the last language group is retained, so pair it with --lang.

For current flags and defaults, run:

nightvision openapi extract --help

For unresolved route values and the other settings available in nv.config, see Configuring Source Intelligence.