| description | Summary and links to CLI tool resource prompts used in CodeQL development |
|---|
This document summarizes and links to the files in this repository that provide "resources" (i.e. static descriptions) of CLI tools that are pre-installed for workspaces created from this repository. These CLI resource prompts are intended for use by GitHub Copilot (or other agentic LLM) in aid of various tasks in the CodeQL development lifecycle.
codeql- The primary, low-level CLI tool for working with individual CodeQL databases, packs, queries, and tests.qlt- A higher-level CLI tool that is useful for tasks such as:- Installing different versions of the
codeqlCLI; - Performing development tasks for multiple CodeQL packs, queries, and/or tests;
- Creating the directories and files required for fully setting up a new query along with its packs and tests.
- Installing different versions of the
The codeql CLI has many subcommands -- we will not use all of them.
Just pick the subcommands from the list below according to your needs.
- codeql bqrs decode - Decode a .bqrs (Binary Query Results Set) file -- the raw output of a query run against a database -- to some human-readable format.
- codeql bqrs info - Display metadata about binary query result files.
- codeql database analyze - Run queries against CodeQL databases and interpret results.
- codeql database create - Create CodeQL databases from source code.
- codeql execute query-server2 - Run a persistent query execution server for IDE integrations and efficient multi-query workflows.
- codeql generate extensible-predicate-metadata - Generate metadata for extensible predicates.
- codeql generate log-summary - Create a summary of structured evaluator log files for performance analysis and debugging.
- codeql generate query-help - Generate help documentation for queries.
- codeql pack install - Install CodeQL packs and their (pack) dependencies.
- codeql pack ls - List available CodeQL packs.
- codeql query compile - Compile CodeQL queries and check for syntax errors.
- codeql query format - Format CodeQL query source code.
- codeql query run - Execute single CodeQL queries against databases.
- codeql resolve database - Resolve database paths and validate database structure.
- codeql resolve extractor - Resolve language extractors and their configurations.
- codeql resolve languages - List supported programming languages and their extractors.
- codeql resolve library-path - Resolve library search paths for CodeQL compilation.
- codeql resolve metadata - Resolve query metadata and pack information.
- codeql resolve queries - Find and resolve query files in packs.
- codeql resolve tests - Discover test files and test suites.
- codeql test accept - Accept test results as new expected outcomes.
- codeql test extract - Extract test databases from source code.
- codeql test run - Execute CodeQL query tests and validate results.
The qlt (CodeQL Development Toolkit) CLI is primarily used for creating the scaffolding for a new query and its packs (if not already created) and unit test setup. For most iterative ql development tasks, the codeql CLI is usually a better choice as the qlt CLI is intended for CI/CD workflows that operate on all the CodeQL queries for some base directory and/or langauge and/or pack. As such, you should only run qlt subcommands (other than qlt query generate new-query) if you are really extra sure that you want to perform operations that affect much more than just one query, pack, or test.
- qlt query generate new-query - Generate the scaffolding for a new CodeQL query, including directories and files for (src & test) packs, the query itself, and unit testing of the query.
- qlt query run install-packs - Install ALL packs, for ALL languages, found under a given
--basedirectory. - qlt test run execute-unit-tests - Execute ALL unit tests for all queries for a given
--basedirectory and/or language. - qlt test run validate-unit-tests - Debug / report on the results from the output directory created by running
qlt test run execute-unit-tests.