awesome-copilot/skills/codeql/references/cli-commands.md

CodeQL CLI Command Reference

Detailed reference for the CodeQL CLI — installation, database creation, analysis, SARIF upload, and CI integration.

Installation

Download the CodeQL Bundle

Always download the CodeQL bundle (CLI + precompiled queries) from: https://github.com/github/codeql-action/releases

The bundle includes:

• CodeQL CLI product
• Compatible queries and libraries from github/codeql
• Precompiled query plans for faster analysis

Platform-Specific Bundles

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.gz variants are also available for systems without Zstandard support.

Setup

# 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 languages

codeql resolve packs should list available query packs for all supported languages. If packs are missing, verify you downloaded the bundle (not standalone CLI).

CI System Setup

Ensure the full CodeQL bundle contents are available on every CI server:

• Copy from a central location and extract on each server, or
• Use the GitHub REST API to download the bundle dynamically per run

Core Commands

codeql database create

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

codeql database analyze

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-contents

codeql github upload-results

Upload 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.

codeql resolve packs

List available query packs:

codeql resolve packs

Use to verify installation and diagnose missing packs. Available since CLI v2.19.0 (earlier versions: use codeql resolve qlpacks).

codeql resolve languages

List supported languages:

codeql resolve languages

Shows which language extractors are available in the current installation.

codeql database bundle

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.

CLI Server Mode

codeql execute cli-server

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.

CI Integration Pattern

Complete CI Script Example

#!/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."
done

External CI Systems

For CI systems other than GitHub Actions:

1. Install the CodeQL bundle on CI runners
2. Run codeql database create with appropriate build commands
3. Run codeql database analyze to generate SARIF
4. Run codeql github upload-results to push results to GitHub
5. Set GITHUB_TOKEN with security-events: write permission

Environment Variables

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