Setting the file. One moment.
Subchapter 78.2
references/cli-commands.mdMarkdown8 KBView on GitHub
Detailed reference for the CodeQL CLI — installation, database creation, analysis, SARIF upload, and CI integration.
Always download the CodeQL bundle (CLI + precompiled queries) from: https://github.com/github/codeql-action/releases (opens in a new tab)
The bundle includes:
github/codeql| Platform | File |
|---|---|
| All platforms | codeql-bundle.tar.zst |
| Linux | codeql-bundle-linux64.tar.zst |
| macOS | codeql-bundle-osx64.tar.zst |
| Windows | codeql-bundle-win64.tar.zst |
.tar.gzvariants are also available for systems without Zstandard support.
# Extract the bundle
tar xf codeql-bundle-linux64.tar.zst
# Add to PATH
export PATH="$HOME/codeql:$PATH"
# Verify installation
codeql resolve packs
codeql resolve languagescodeql resolve packs should list available query packs for all supported languages. If packs are missing, verify you downloaded the bundle (not standalone CLI).
Ensure the full CodeQL bundle contents are available on every CI server:
Create a CodeQL database from source code.
# Basic usage (interpreted language)
codeql database create <output-dir> \
--language=<language> \
--source-root=<source-dir>
# Compiled language with build command
codeql database create <output-dir> \
--language=java-kotlin \
--command='./gradlew build' \
--source-root=.
# Multiple languages (cluster mode)
codeql database create <output-dir> \
--db-cluster \
--language=java,python,javascript-typescript \
--command='./build.sh' \
--source-root=.Key flags:
| Flag | Description |
|---|---|
--language=<lang> | Language to extract (required). Use CodeQL language identifiers. |
--source-root=<dir> | Root directory of source code (default: current directory) |
--command=<cmd> | Build command for compiled languages |
--db-cluster | Create databases for multiple languages in one pass |
--overwrite | Overwrite existing database directory |
--threads=<n> | Number of threads for extraction (default: 1; use 0 for all available cores) |
--ram=<mb> | RAM limit in MB for extraction |
Run queries against a CodeQL database and produce SARIF output.
codeql database analyze <database-dir> \
<query-suite-or-pack> \
--format=sarif-latest \
--sarif-category=<category> \
--output=<output-file>Key flags:
| Flag | Description |
|---|---|
--format=sarif-latest | Output format (use sarif-latest for current SARIF v2.1.0) |
--sarif-category=<cat> | Category tag for the SARIF results (important for multi-language repos) |
--output=<file> | Output file path for SARIF results |
--threads=<n> | Number of threads for analysis |
--ram=<mb> | RAM limit in MB |
--sarif-add-file-contents | Include source file contents in SARIF output |
--ungroup-results | Disable result grouping (each occurrence reported separately) |
--no-download | Skip downloading query packs (use only locally available packs) |
Common query suites:
| Suite | Description |
|---|---|
<lang>-code-scanning.qls | Standard code scanning queries |
<lang>-security-extended.qls | Extended security queries |
<lang>-security-and-quality.qls | Security + code quality queries |
Examples:
# JavaScript analysis with extended security
codeql database analyze codeql-db/javascript-typescript \
javascript-typescript-security-extended.qls \
--format=sarif-latest \
--sarif-category=javascript \
--output=js-results.sarif
# Java analysis with all available threads
codeql database analyze codeql-db/java-kotlin \
java-kotlin-code-scanning.qls \
--format=sarif-latest \
--sarif-category=java \
--output=java-results.sarif \
--threads=0
# Include file contents in SARIF
codeql database analyze codeql-db \
javascript-typescript-code-scanning.qls \
--format=sarif-latest \
--output=results.sarif \
--sarif-add-file-contentsUpload SARIF results to GitHub code scanning.
codeql github upload-results \
--repository=<owner/repo> \
--ref=<git-ref> \
--commit=<commit-sha> \
--sarif=<sarif-file>Key flags:
| Flag | Description |
|---|---|
--repository=<owner/repo> | Target GitHub repository |
--ref=<ref> | Git ref (e.g., refs/heads/main, refs/pull/42/head) |
--commit=<sha> | Full commit SHA |
--sarif=<file> | Path to SARIF file |
--github-url=<url> | GitHub instance URL (for GHES; defaults to github.com) |
--github-auth-stdin | Read auth token from stdin instead of GITHUB_TOKEN env var |
Authentication: Set GITHUB_TOKEN environment variable with a token that has security-events: write scope, or use --github-auth-stdin.
List available query packs:
codeql resolve packsUse to verify installation and diagnose missing packs. Available since CLI v2.19.0 (earlier versions: use codeql resolve qlpacks).
List supported languages:
codeql resolve languagesShows which language extractors are available in the current installation.
Create a relocatable archive of a CodeQL database for sharing or troubleshooting:
codeql database bundle <database-dir> \
--output=<archive-file>Useful for sharing databases with team members or GitHub Support.
Run a persistent server to avoid repeated JVM initialization when executing multiple commands:
codeql execute cli-server [options]Key flags:
| Flag | Description |
|---|---|
-v, --verbose | Increase progress messages |
-q, --quiet | Decrease progress messages |
--verbosity=<level> | Set verbosity: errors, warnings, progress, progress+, progress++, progress+++ |
--logdir=<dir> | Write detailed logs to directory |
--common-caches=<dir> | Location for persistent cached data (default: ~/.codeql) |
-J=<opt> | Pass option to the JVM |
The server accepts commands via stdin and returns results, keeping the JVM warm between commands. Primarily useful in CI environments running multiple sequential CodeQL commands.
#!/bin/bash
set -euo pipefail
REPO="my-org/my-repo"
REF="refs/heads/main"
COMMIT=$(git rev-parse HEAD)
LANGUAGES=("javascript-typescript" "python")
# Create databases for all languages
codeql database create codeql-dbs \
--db-cluster \
--source-root=. \
--language=$(IFS=,; echo "${LANGUAGES[*]}")
# Analyze each language and upload results
for lang in "${LANGUAGES[@]}"; do
echo "Analyzing $lang..."
codeql database analyze "codeql-dbs/$lang" \
"${lang}-security-extended.qls" \
--format=sarif-latest \
--sarif-category="$lang" \
--output="${lang}-results.sarif" \
--threads=0
codeql github upload-results \
--repository="$REPO" \
--ref="$REF" \
--commit="$COMMIT" \
--sarif="${lang}-results.sarif"
echo "$lang analysis uploaded."
doneFor CI systems other than GitHub Actions:
codeql database create with appropriate build commandscodeql database analyze to generate SARIFcodeql github upload-results to push results to GitHubGITHUB_TOKEN with security-events: write permission| Variable | Purpose |
|---|---|
GITHUB_TOKEN | Authentication for github upload-results |
CODEQL_EXTRACTOR_<LANG>_OPTION_<KEY> | Extractor configuration (e.g., CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS=true) |
CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES | Auto-install C/C++ build dependencies on Ubuntu |
CODEQL_RAM | Override default RAM allocation for analysis |
CODEQL_THREADS | Override default thread count |