Docs: Update analyzing databases docs

Add more information about running packs. Include the `--download` flag.

Author: aeisenberg

docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst

@@ -26,6 +26,7 @@ Running ``codeql database analyze``
 
 When you run ``database analyze``, it:
 
+#. Optionally downloads any referenced CodeQL packages that are not available locally.
 #. Executes one or more query files, by running them over a CodeQL database.
 #. Interprets the results, based on certain query metadata, so that alerts can be
    displayed in the correct location in the source code.
@@ -50,10 +51,13 @@ You must specify:
 
 You can also specify:
 
-- ``<queries>``: the queries to run over your database. You can
-  list one or more individual query files, specify a directory that will be
-  searched recursively for query files, or name a query suite that defines a
-  particular set of queries. If omitted, the default query suite for the language
+- ``...<query-specifications>``: a list of queries to run over your database. This
+  is a list of arguments. Where each argument can be:
+  - a path to a query file
+  - a path to a directory containing query files
+  - a path to a query suite file
+  - the name of a CodeQL query pack
+  If omitted, the default query suite for the language
   of the database being analyzed will be usedFor more information, see the
   :ref:`examples <database-analyze-examples>` below.
 
@@ -63,11 +67,14 @@ You can also specify:
   language to the GitHub code scanning API. For more information about this use case,
   see `Configuring CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system>`__ in the GitHub documentation.
 
-- ``--sarif-add-query-help``: (supported in version 2.7.1 onwards) adds any custom query help written 
-   in markdown to SARIF files (v2.1.0 or later) generated by the analysis. Query help stored in ``.qhelp`` files must be 
-   converted to ``.md`` before running the analysis. For further information, 
+- ``--sarif-add-query-help``: (supported in version 2.7.1 onwards) adds any custom query help written
+   in markdown to SARIF files (v2.1.0 or later) generated by the analysis. Query help stored in ``.qhelp`` files must be
+   converted to ``.md`` before running the analysis. For further information,
    see ":ref:`Including query help for custom CodeQL queries in SARIF files  <including-query-help-for-custom-codeql-queries-in-sarif-files>`."
 
+- ``--download``: a boolean flag that will allow the CLI to download  any referenced CodeQL packages that are not available locally.
+   If this flag is missing and a referenced CodeQL package is not available locally, the command will fail.
+
 - .. include:: ../reusables/threads-query-execution.rst
 
 
@@ -119,17 +126,16 @@ Running a CodeQL pack
 
 .. include:: ../reusables/beta-note-package-management.rst
 
-To run an existing CodeQL query pack from the GitHub Container registry, you need to download it first::
-
-   codeql pack download microsoft/[email protected]
+To run an existing CodeQL query pack from the GitHub Container registry, you can specify one or more
+pack names and use the ``--download`` flag::
 
-Afterwards, you can run the pack on a specific database::
+   codeql database analyze --download <database> microsoft/[email protected] github/secutiry-queries --format=sarifv2.1.0 --output=query-results.sarif
 
-   codeql database analyze <database> microsoft/[email protected] <scope>/<other-pack> --format=sarifv2.1.0 --output=query-results.sarif
-
-The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``scope/other-pack`` on the specified database.
+The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``github/secutiry-queries`` on the specified database.
 For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
 
+For more information about CodeQL packs, see :doc:`About CodeQL Packs <about-codeql-packs>`.
+
 Running query suites
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -176,7 +182,7 @@ Integrating a CodeQL pack into a code scanning workflow in GitHub
 
 .. include:: ../reusables/beta-note-package-management.rst
 
-You can use CodeQL query packs in your Code Scanning setup. This allows you to select query packs published by various sources and use them to analyze your code. 
+You can use CodeQL query packs in your Code Scanning setup. This allows you to select query packs published by various sources and use them to analyze your code.
 For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_."
 
 
@@ -206,28 +212,28 @@ A SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
 that the results are formatted according to the most recent SARIF specification
 supported by CodeQL.
 
-.. _including-query-help-for-custom-codeql-queries-in-sarif-files: 
+.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
 
-Including query help for custom CodeQL queries in SARIF files 
+Including query help for custom CodeQL queries in SARIF files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you use the CodeQL CLI to to run code scanning analyses on third party CI/CD systems,
 you can include the query help for your custom queries in SARIF files generated during an analysis.
-After uploading the SARIF file to GitHub, the query help is shown in the code scanning UI for any 
-alerts generated by the custom queries. 
+After uploading the SARIF file to GitHub, the query help is shown in the code scanning UI for any
+alerts generated by the custom queries.
 
-From CodeQL CLI 2.7.1 onwards, you can include markdown-rendered query help in SARIF files 
+From CodeQL CLI 2.7.1 onwards, you can include markdown-rendered query help in SARIF files
 by providing the ``--sarif-add-query-help`` option when running
-``codeql database analyze``. 
+``codeql database analyze``.
 For more information, see `Configuring CodeQL CLI in your CI system <https://docs.github.com/en/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__
 in the GitHub documentation.
 
 You can write query help for custom queries directly in a markdown file and save it alongside the
-corresponding query. Alternatively, for consistency with the standard CodeQL queries, 
-you can write query help in the ``.qhelp`` format. Query help written in ``.qhelp`` 
+corresponding query. Alternatively, for consistency with the standard CodeQL queries,
+you can write query help in the ``.qhelp`` format. Query help written in ``.qhelp``
 files can't be included in SARIF files, and they can't be processed by code
-scanning so must be converted to markdown before running 
-the analysis. For more information, see ":ref:`Query help files <query-help-files>`" 
+scanning so must be converted to markdown before running
+the analysis. For more information, see ":ref:`Query help files <query-help-files>`"
 and ":doc:`Testing query help files <testing-query-help-files>`."
 
 Results