Update CodeQL CLI manual (#36086)
Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>
This commit is contained in:
docubot
@@ -0,0 +1,144 @@
|
||||
---
|
||||
title: database add-diagnostic
|
||||
intro: '[Experimental] Add a piece of diagnostic information to a database.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Advanced Security
|
||||
- Code scanning
|
||||
- CodeQL
|
||||
type: reference
|
||||
product: '{% data reusables.gated-features.codeql %}'
|
||||
autogenerated: codeql-cli
|
||||
---
|
||||
{% data reusables.codeql-cli.man-pages-version-note %}
|
||||
|
||||
## Synopsis
|
||||
|
||||
```shell{:copy}
|
||||
codeql database add-diagnostic --source-id=<id> --source-name=<name> <options>... -- <database>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
\[Experimental] Add a piece of diagnostic information to a database.
|
||||
|
||||
## Primary options
|
||||
|
||||
#### `<database>`
|
||||
|
||||
\[Mandatory] Path to the CodeQL database to bundle.
|
||||
|
||||
#### `--markdown-message=<markdownMessage>`
|
||||
|
||||
Message for the diagnostic, in GitHub-flavored Markdown format.
|
||||
|
||||
#### `--plaintext-message=<plaintextMessage>`
|
||||
|
||||
Message for the diagnostic, in plain text. This option should only be
|
||||
used when populating a Markdown message with --markdown-message is not
|
||||
practical.
|
||||
|
||||
#### `--severity=<severity>`
|
||||
|
||||
Severity of the diagnostic. Can be "error", "warning", or "note".
|
||||
|
||||
#### `--help-link=<helpLinks>`
|
||||
|
||||
Help links relevant to the diagnostic.
|
||||
|
||||
#### `--attributes-json=<attributesJson>`
|
||||
|
||||
Structured metadata relevant to the diagnostic.
|
||||
|
||||
### Options that indicate where the diagnostic message can be displayed
|
||||
|
||||
#### `--ready-for-status-page`
|
||||
|
||||
Indicate that the diagnostic is suitable for display on the status page.
|
||||
|
||||
#### `--ready-for-cli-summary-table`
|
||||
|
||||
Indicate that the diagnostic is suitable for display in the diagnostics
|
||||
summary table printed by commands like `database analyze`.
|
||||
|
||||
### Options describing the source of the diagnostic
|
||||
|
||||
#### `--source-id=<id>`
|
||||
|
||||
\[Mandatory] An identifier for the source of this diagnostic.
|
||||
|
||||
#### `--source-name=<name>`
|
||||
|
||||
\[Mandatory] A human-readable description of the source of this
|
||||
diagnostic.
|
||||
|
||||
#### `--extractor-name=<extractorName>`
|
||||
|
||||
The name of the CodeQL extractor, if this diagnostic was produced by a
|
||||
CodeQL extractor.
|
||||
|
||||
### Options describing the diagnostic's location
|
||||
|
||||
#### `--file-path=<file>`
|
||||
|
||||
The path of the file to which the diagnostic applies, relative to the
|
||||
source root.
|
||||
|
||||
#### `--start-line=<startLine>`
|
||||
|
||||
The 1-based line number (inclusive) where the diagnostic's location
|
||||
starts.
|
||||
|
||||
#### `--start-column=<startColumn>`
|
||||
|
||||
The 1-based column number (inclusive) where the diagnostic's location
|
||||
starts.
|
||||
|
||||
#### `--end-line=<endLine>`
|
||||
|
||||
The 1-based line number (inclusive) where the diagnostic's location
|
||||
ends.
|
||||
|
||||
#### `--end-column=<endColumn>`
|
||||
|
||||
The 1-based column number (inclusive) where the diagnostic's location
|
||||
ends.
|
||||
|
||||
### Common options
|
||||
|
||||
#### `-h, --help`
|
||||
|
||||
Show this help text.
|
||||
|
||||
#### `-J=<opt>`
|
||||
|
||||
\[Advanced] Give option to the JVM running the command.
|
||||
|
||||
(Beware that options containing spaces will not be handled correctly.)
|
||||
|
||||
#### `-v, --verbose`
|
||||
|
||||
Incrementally increase the number of progress messages printed.
|
||||
|
||||
#### `-q, --quiet`
|
||||
|
||||
Incrementally decrease the number of progress messages printed.
|
||||
|
||||
#### `--verbosity=<level>`
|
||||
|
||||
\[Advanced] Explicitly set the verbosity level to one of errors,
|
||||
warnings, progress, progress+, progress++, progress+++. Overrides `-v`
|
||||
and `-q`.
|
||||
|
||||
#### `--logdir=<dir>`
|
||||
|
||||
\[Advanced] Write detailed logs to one or more files in the given
|
||||
directory, with generated names that include timestamps and the name of
|
||||
the running subcommand.
|
||||
|
||||
(To write a log file with a name you have full control over, instead
|
||||
give `--log-to-stderr` and redirect stderr as desired.)
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: database export-diagnostics
|
||||
intro: |-
|
||||
[Experimental] Export diagnostic information from a database for a
|
||||
failed analysis.
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Advanced Security
|
||||
- Code scanning
|
||||
- CodeQL
|
||||
type: reference
|
||||
product: '{% data reusables.gated-features.codeql %}'
|
||||
autogenerated: codeql-cli
|
||||
---
|
||||
{% data reusables.codeql-cli.man-pages-version-note %}
|
||||
|
||||
## Synopsis
|
||||
|
||||
```shell{:copy}
|
||||
codeql database export-diagnostics --format=<format> [--output=<output>] <options>... -- <database>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
\[Experimental] Export diagnostic information from a database for a
|
||||
failed analysis.
|
||||
|
||||
## Primary options
|
||||
|
||||
#### `<database>`
|
||||
|
||||
\[Mandatory] Path to the CodeQL database under construction. This must
|
||||
have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init).
|
||||
|
||||
If the `--db-cluster` option is given, this is not a database itself,
|
||||
but a directory that *contains* databases, and all of those databases
|
||||
will be processed together.
|
||||
|
||||
#### `--format=<format>`
|
||||
|
||||
\[Mandatory] The format in which to write the results. One of:
|
||||
|
||||
`raw`: A list of raw, uninterpreted diagnostic messages as JSON objects.
|
||||
|
||||
`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a
|
||||
JSON-based format for describing static analysis results. This format
|
||||
option uses the most recent supported version (v2.1.0). This option is
|
||||
not suitable for use in automation as it will produce different versions
|
||||
of SARIF between different CodeQL versions.
|
||||
|
||||
`sarifv2.1.0`: SARIF v2.1.0.
|
||||
|
||||
`text`: A bullet point list of diagnostic messages.
|
||||
|
||||
#### `--[no-]db-cluster`
|
||||
|
||||
Indicates that the directory given on the command line is not a database
|
||||
itself, but a directory that *contains* one or more databases under
|
||||
construction. Those databases will be processed together.
|
||||
|
||||
#### `-o, --output=<output>`
|
||||
|
||||
The output path to write diagnostic information to.
|
||||
|
||||
#### `--sarif-exit-code=<sarifExitCode>`
|
||||
|
||||
\[SARIF formats only] Exit code of the failing process.
|
||||
|
||||
#### `--sarif-exit-code-description=<sarifExitCodeDescription>`
|
||||
|
||||
\[SARIF formats only] Reason that the failing process exited.
|
||||
|
||||
#### `--sarif-category=<category>`
|
||||
|
||||
\[SARIF formats only] Specify a category for this analysis to include
|
||||
in the SARIF output. A category can be used to distinguish multiple
|
||||
analyses performed on the same commit and repository, but on different
|
||||
languages or different parts of the code.
|
||||
|
||||
If you analyze the same version of a code base in several different ways
|
||||
(e.g., for different languages) and upload the results to GitHub for
|
||||
presentation in Code Scanning, this value should differ between each of
|
||||
the analyses, which tells Code Scanning that the analyses *supplement*
|
||||
rather than *supersede* each other. (The values should be consistent
|
||||
between runs of the same analysis for *different* versions of the code
|
||||
base.)
|
||||
|
||||
This value will appear (with a trailing slash appended if not already
|
||||
present) as the `<run>.automationId` property in SARIF v1, the
|
||||
`<run>.automationLogicalId` property in SARIF v2, and the
|
||||
`<run>.automationDetails.id` property in SARIF v2.1.0.
|
||||
|
||||
### Common options
|
||||
|
||||
#### `-h, --help`
|
||||
|
||||
Show this help text.
|
||||
|
||||
#### `-J=<opt>`
|
||||
|
||||
\[Advanced] Give option to the JVM running the command.
|
||||
|
||||
(Beware that options containing spaces will not be handled correctly.)
|
||||
|
||||
#### `-v, --verbose`
|
||||
|
||||
Incrementally increase the number of progress messages printed.
|
||||
|
||||
#### `-q, --quiet`
|
||||
|
||||
Incrementally decrease the number of progress messages printed.
|
||||
|
||||
#### `--verbosity=<level>`
|
||||
|
||||
\[Advanced] Explicitly set the verbosity level to one of errors,
|
||||
warnings, progress, progress+, progress++, progress+++. Overrides `-v`
|
||||
and `-q`.
|
||||
|
||||
#### `--logdir=<dir>`
|
||||
|
||||
\[Advanced] Write detailed logs to one or more files in the given
|
||||
directory, with generated names that include timestamps and the name of
|
||||
the running subcommand.
|
||||
|
||||
(To write a log file with a name you have full control over, instead
|
||||
give `--log-to-stderr` and redirect stderr as desired.)
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: diagnostic add
|
||||
intro: '[Experimental] [Plumbing] Add a piece of diagnostic information.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Advanced Security
|
||||
- Code scanning
|
||||
- CodeQL
|
||||
type: reference
|
||||
product: '{% data reusables.gated-features.codeql %}'
|
||||
autogenerated: codeql-cli
|
||||
---
|
||||
{% data reusables.codeql-cli.man-pages-version-note %}
|
||||
|
||||
## Synopsis
|
||||
|
||||
```shell{:copy}
|
||||
codeql diagnostic add (--diagnostic-dir=<diagnosticDir>) --source-id=<id> --source-name=<name> <options>...
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
\[Experimental] \[Plumbing] Add a piece of diagnostic information.
|
||||
|
||||
## Primary options
|
||||
|
||||
#### `--markdown-message=<markdownMessage>`
|
||||
|
||||
Message for the diagnostic, in GitHub-flavored Markdown format.
|
||||
|
||||
#### `--plaintext-message=<plaintextMessage>`
|
||||
|
||||
Message for the diagnostic, in plain text. This option should only be
|
||||
used when populating a Markdown message with --markdown-message is not
|
||||
practical.
|
||||
|
||||
#### `--severity=<severity>`
|
||||
|
||||
Severity of the diagnostic. Can be "error", "warning", or "note".
|
||||
|
||||
#### `--help-link=<helpLinks>`
|
||||
|
||||
Help links relevant to the diagnostic.
|
||||
|
||||
#### `--attributes-json=<attributesJson>`
|
||||
|
||||
Structured metadata relevant to the diagnostic.
|
||||
|
||||
### Options specifying where to save the diagnostic information
|
||||
|
||||
Exactly one of these options must be given.
|
||||
|
||||
#### `--diagnostic-dir=<diagnosticDir>`
|
||||
|
||||
Directory to which we should add the diagnostic.
|
||||
|
||||
### Options that indicate where the diagnostic message can be displayed
|
||||
|
||||
#### `--ready-for-status-page`
|
||||
|
||||
Indicate that the diagnostic is suitable for display on the status page.
|
||||
|
||||
#### `--ready-for-cli-summary-table`
|
||||
|
||||
Indicate that the diagnostic is suitable for display in the diagnostics
|
||||
summary table printed by commands like `database analyze`.
|
||||
|
||||
### Options describing the source of the diagnostic
|
||||
|
||||
#### `--source-id=<id>`
|
||||
|
||||
\[Mandatory] An identifier for the source of this diagnostic.
|
||||
|
||||
#### `--source-name=<name>`
|
||||
|
||||
\[Mandatory] A human-readable description of the source of this
|
||||
diagnostic.
|
||||
|
||||
#### `--extractor-name=<extractorName>`
|
||||
|
||||
The name of the CodeQL extractor, if this diagnostic was produced by a
|
||||
CodeQL extractor.
|
||||
|
||||
### Options describing the diagnostic's location
|
||||
|
||||
#### `--file-path=<file>`
|
||||
|
||||
The path of the file to which the diagnostic applies, relative to the
|
||||
source root.
|
||||
|
||||
#### `--start-line=<startLine>`
|
||||
|
||||
The 1-based line number (inclusive) where the diagnostic's location
|
||||
starts.
|
||||
|
||||
#### `--start-column=<startColumn>`
|
||||
|
||||
The 1-based column number (inclusive) where the diagnostic's location
|
||||
starts.
|
||||
|
||||
#### `--end-line=<endLine>`
|
||||
|
||||
The 1-based line number (inclusive) where the diagnostic's location
|
||||
ends.
|
||||
|
||||
#### `--end-column=<endColumn>`
|
||||
|
||||
The 1-based column number (inclusive) where the diagnostic's location
|
||||
ends.
|
||||
|
||||
### Common options
|
||||
|
||||
#### `-h, --help`
|
||||
|
||||
Show this help text.
|
||||
|
||||
#### `-J=<opt>`
|
||||
|
||||
\[Advanced] Give option to the JVM running the command.
|
||||
|
||||
(Beware that options containing spaces will not be handled correctly.)
|
||||
|
||||
#### `-v, --verbose`
|
||||
|
||||
Incrementally increase the number of progress messages printed.
|
||||
|
||||
#### `-q, --quiet`
|
||||
|
||||
Incrementally decrease the number of progress messages printed.
|
||||
|
||||
#### `--verbosity=<level>`
|
||||
|
||||
\[Advanced] Explicitly set the verbosity level to one of errors,
|
||||
warnings, progress, progress+, progress++, progress+++. Overrides `-v`
|
||||
and `-q`.
|
||||
|
||||
#### `--logdir=<dir>`
|
||||
|
||||
\[Advanced] Write detailed logs to one or more files in the given
|
||||
directory, with generated names that include timestamps and the name of
|
||||
the running subcommand.
|
||||
|
||||
(To write a log file with a name you have full control over, instead
|
||||
give `--log-to-stderr` and redirect stderr as desired.)
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: diagnostic export
|
||||
intro: '[Experimental] Export diagnostic information for a failed analysis.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Advanced Security
|
||||
- Code scanning
|
||||
- CodeQL
|
||||
type: reference
|
||||
product: '{% data reusables.gated-features.codeql %}'
|
||||
autogenerated: codeql-cli
|
||||
---
|
||||
{% data reusables.codeql-cli.man-pages-version-note %}
|
||||
|
||||
## Synopsis
|
||||
|
||||
```shell{:copy}
|
||||
codeql diagnostic export --format=<format> [--output=<output>] <options>...
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
\[Experimental] Export diagnostic information for a failed analysis.
|
||||
|
||||
## Primary options
|
||||
|
||||
#### `--format=<format>`
|
||||
|
||||
\[Mandatory] The format in which to write the results. One of:
|
||||
|
||||
`raw`: A list of raw, uninterpreted diagnostic messages as JSON objects.
|
||||
|
||||
`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a
|
||||
JSON-based format for describing static analysis results. This format
|
||||
option uses the most recent supported version (v2.1.0). This option is
|
||||
not suitable for use in automation as it will produce different versions
|
||||
of SARIF between different CodeQL versions.
|
||||
|
||||
`sarifv2.1.0`: SARIF v2.1.0.
|
||||
|
||||
`text`: A bullet point list of diagnostic messages.
|
||||
|
||||
#### `-o, --output=<output>`
|
||||
|
||||
The output path to write diagnostic information to.
|
||||
|
||||
#### `--sarif-exit-code=<sarifExitCode>`
|
||||
|
||||
\[SARIF formats only] Exit code of the failing process.
|
||||
|
||||
#### `--sarif-exit-code-description=<sarifExitCodeDescription>`
|
||||
|
||||
\[SARIF formats only] Reason that the failing process exited.
|
||||
|
||||
#### `--sarif-category=<category>`
|
||||
|
||||
\[SARIF formats only] Specify a category for this analysis to include
|
||||
in the SARIF output. A category can be used to distinguish multiple
|
||||
analyses performed on the same commit and repository, but on different
|
||||
languages or different parts of the code.
|
||||
|
||||
If you analyze the same version of a code base in several different ways
|
||||
(e.g., for different languages) and upload the results to GitHub for
|
||||
presentation in Code Scanning, this value should differ between each of
|
||||
the analyses, which tells Code Scanning that the analyses *supplement*
|
||||
rather than *supersede* each other. (The values should be consistent
|
||||
between runs of the same analysis for *different* versions of the code
|
||||
base.)
|
||||
|
||||
This value will appear (with a trailing slash appended if not already
|
||||
present) as the `<run>.automationId` property in SARIF v1, the
|
||||
`<run>.automationLogicalId` property in SARIF v2, and the
|
||||
`<run>.automationDetails.id` property in SARIF v2.1.0.
|
||||
|
||||
#### `--diagnostic-dir=<diagnosticDirs>`
|
||||
|
||||
Directory containing CodeQL diagnostic messages. You can pass this
|
||||
multiple times to include multiple directories.
|
||||
|
||||
### Common options
|
||||
|
||||
#### `-h, --help`
|
||||
|
||||
Show this help text.
|
||||
|
||||
#### `-J=<opt>`
|
||||
|
||||
\[Advanced] Give option to the JVM running the command.
|
||||
|
||||
(Beware that options containing spaces will not be handled correctly.)
|
||||
|
||||
#### `-v, --verbose`
|
||||
|
||||
Incrementally increase the number of progress messages printed.
|
||||
|
||||
#### `-q, --quiet`
|
||||
|
||||
Incrementally decrease the number of progress messages printed.
|
||||
|
||||
#### `--verbosity=<level>`
|
||||
|
||||
\[Advanced] Explicitly set the verbosity level to one of errors,
|
||||
warnings, progress, progress+, progress++, progress+++. Overrides `-v`
|
||||
and `-q`.
|
||||
|
||||
#### `--logdir=<dir>`
|
||||
|
||||
\[Advanced] Write detailed logs to one or more files in the given
|
||||
directory, with generated names that include timestamps and the name of
|
||||
the running subcommand.
|
||||
|
||||
(To write a log file with a name you have full control over, instead
|
||||
give `--log-to-stderr` and redirect stderr as desired.)
|
||||
@@ -1,7 +1,9 @@
|
||||
---
|
||||
title: CodeQL CLI commands manual
|
||||
shortTitle: CodeQL CLI manual
|
||||
intro: 'Reference information for the commands available in the most recent release of {% data variables.product.prodname_codeql_cli %}.'
|
||||
intro: >-
|
||||
Reference information for the commands available in the most recent release of
|
||||
{% data variables.product.prodname_codeql_cli %}.
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
@@ -20,10 +22,12 @@ children:
|
||||
- /bqrs-hash
|
||||
- /bqrs-info
|
||||
- /bqrs-interpret
|
||||
- /database-add-diagnostic
|
||||
- /database-analyze
|
||||
- /database-bundle
|
||||
- /database-cleanup
|
||||
- /database-create
|
||||
- /database-export-diagnostics
|
||||
- /database-finalize
|
||||
- /database-import
|
||||
- /database-index-files
|
||||
@@ -39,6 +43,8 @@ children:
|
||||
- /dataset-import
|
||||
- /dataset-measure
|
||||
- /dataset-upgrade
|
||||
- /diagnostic-add
|
||||
- /diagnostic-export
|
||||
- /execute-cli-server
|
||||
- /execute-language-server
|
||||
- /execute-queries
|
||||
|
||||
Reference in New Issue
Block a user