This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent can run shell commands in a repository, it can use the CodeQL CLI to search the code for security issues. The CodeQL CLI turns source code into a CodeQL database, a structured collection of information about relationships in the code. CodeQL runs queries, which search that information for patterns such as data moving from an input to an unsafe use.
Coding agents use the same CodeQL CLI as other users. An agent can analyze a database on its machine and read the results. This helps it check a code path after making a change, as long as the database reflects the current source and the query supports the language. A finding gives the agent something to review; it does not prove that an attacker can exploit the code.
Install and check the CLI
Follow GitHub’s CodeQL CLI setup instructions to install the CLI and make the codeql command available in the shell. GitHub recommends the CodeQL bundle, which contains the CLI together with compatible queries and libraries. Then confirm that the shell can find it:
codeql version
Check the license before you use it on private code. GitHub’s documentation says CodeQL is available for public repositories under the GitHub CodeQL Terms and Conditions. Organization-owned repositories need GitHub Code Security enabled.
The local analysis example below does not require a GitHub login. Creating a database and running a query happen on the machine where the commands run. Sending results to GitHub is a separate network action that requires GitHub authentication; keep any token in the environment or credential store rather than in an agent prompt.
Create a local database and run a query
For a JavaScript or TypeScript repository, an agent can create a database from the current source tree. Set SOURCE to the repository directory and DB to a new database directory:
SOURCE="/path/to/repository"
DB="/path/to/codeql-database"
codeql database create "$DB" \
--language=javascript-typescript \
--source-root="$SOURCE"
Both paths are placeholders. Replace them with real paths on your machine. The guide to preparing code says the command fails if the database directory already exists. If the project has TypeScript files, Node.js 14 or higher must be on the PATH. Keep --language in the command. Without it, the CLI calls the GitHub API to detect the languages of a GitHub checkout. CodeQL extracts information from the source when it creates the database. For compiled languages, CodeQL also needs to run the build or observe it while it runs.
Next, set OUT to the SARIF output path and run the standard JavaScript and TypeScript queries from the bundle:
OUT="/tmp/codeql-results.sarif"
codeql database analyze "$DB" codeql/javascript-queries \
--format=sarifv2.1.0 \
--output="$OUT"
The database analyze reference describes the format and output options. A pack name without a path runs that pack’s default query suite. The reference says sarif-latest can produce different SARIF versions between CodeQL versions and is not suitable for automation, so the example asks for sarifv2.1.0. SARIF is a JSON-based format for results from static analysis, which checks code without running it. This command saves results to a local file and does not upload them to GitHub.
codeql query run runs a single .ql file, but the query-run reference says it writes results in the binary BQRS format. It points to database analyze for SARIF output. A coding agent can use a query from an installed CodeQL query pack, a collection of CodeQL queries, or use custom queries already in the repository. If the agent edits source after creating the database, it must recreate the database before running the queries so the analysis includes those edits.
Review findings as leads
The agent should inspect each result in context: where potentially unsafe data enters the code, where it goes, and whether the code applies safeguards along the way. Static analysis checks for patterns described by its queries. It cannot show how every input behaves when the code runs, and a clean result does not prove that the code is secure.
A concise prompt for a local review could be:
Use the installed CodeQL CLI to check the changed JavaScript or TypeScript code. Create or refresh a local database for the current repository, run the standard JavaScript queries, and inspect the SARIF results. Report each finding with its source location and relevant code path. Do not upload results or change files.
If the agent needs to publish findings, make that a separate, explicit step. GitHub’s CodeQL CLI documentation describes codeql github upload-results and other ways to use the CLI beyond running queries locally.