From 0b817944f7601408cfa0a076a78dbbde3808f5ea Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sun, 21 May 2023 13:44:01 -0700
Subject: [PATCH] Reformatted CLI examples in docs, refs #551

---
 docs/_templates/base.html |    5 +
 docs/cli.rst              | 1183 ++++++++++++++++++++++++++-----------
 2 files changed, 846 insertions(+), 342 deletions(-)

diff --git a/docs/_templates/base.html b/docs/_templates/base.html
index 43c2003..a253a46 100644
--- a/docs/_templates/base.html
+++ b/docs/_templates/base.html
@@ -7,6 +7,11 @@
 
 {% block scripts %}
 {{ super() }}
+<style type="text/css">
+.highlight-output .highlight {
+  border-left: 9px solid #30c94f;
+}
+</style>
 <script>
 document.addEventListener("DOMContentLoaded", function() {
   // Show banner linking to /stable/ if this is a /latest/ page
diff --git a/docs/cli.rst b/docs/cli.rst
index 3b9ac31..5c75502 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -16,10 +16,15 @@ Once :ref:`installed <installation>` the tool should be available as ``sqlite-ut
 Running SQL queries
 ===================
 
-The ``sqlite-utils query`` command lets you run queries directly against a SQLite database file. This is the default subcommand, so the following two examples work the same way::
+The ``sqlite-utils query`` command lets you run queries directly against a SQLite database file. This is the default subcommand, so the following two examples work the same way:
 
-    $ sqlite-utils query dogs.db "select * from dogs"
-    $ sqlite-utils dogs.db "select * from dogs"
+.. code-block:: bash
+
+    sqlite-utils query dogs.db "select * from dogs"
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs"
 
 .. note::
     In Python: :ref:`db.query() <python_api_query>`  CLI reference: :ref:`sqlite-utils query <cli_ref_query>`
@@ -29,9 +34,14 @@ The ``sqlite-utils query`` command lets you run queries directly against a SQLit
 Returning JSON
 --------------
 
-The default format returned for queries is JSON::
+The default format returned for queries is JSON:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs"
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs"
     [{"id": 1, "age": 4, "name": "Cleo"},
      {"id": 2, "age": 2, "name": "Pancakes"}]
 
@@ -40,9 +50,14 @@ The default format returned for queries is JSON::
 Newline-delimited JSON
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Use ``--nl`` to get back newline-delimited JSON objects::
+Use ``--nl`` to get back newline-delimited JSON objects:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --nl
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --nl
     {"id": 1, "age": 4, "name": "Cleo"}
     {"id": 2, "age": 2, "name": "Pancakes"}
 
@@ -51,21 +66,36 @@ Use ``--nl`` to get back newline-delimited JSON objects::
 JSON arrays
 ~~~~~~~~~~~
 
-You can use ``--arrays`` to request arrays instead of objects::
+You can use ``--arrays`` to request arrays instead of objects:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --arrays
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --arrays
     [[1, 4, "Cleo"],
      [2, 2, "Pancakes"]]
 
-You can also combine ``--arrays`` and ``--nl``::
+You can also combine ``--arrays`` and ``--nl``:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --arrays --nl
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --arrays --nl 
     [1, 4, "Cleo"]
     [2, 2, "Pancakes"]
 
-If you want to pretty-print the output further, you can pipe it through ``python -mjson.tool``::
+If you want to pretty-print the output further, you can pipe it through ``python -mjson.tool``:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" | python -mjson.tool
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" | python -mjson.tool
     [
         {
             "id": 1,
@@ -84,9 +114,14 @@ If you want to pretty-print the output further, you can pipe it through ``python
 Binary data in JSON
 ~~~~~~~~~~~~~~~~~~~
 
-Binary strings are not valid JSON, so BLOB columns containing binary data will be returned as a JSON object containing base64 encoded data, that looks like this::
+Binary strings are not valid JSON, so BLOB columns containing binary data will be returned as a JSON object containing base64 encoded data, that looks like this:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select name, content from images" | python -mjson.tool
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select name, content from images" | python -mjson.tool
     [
         {
             "name": "transparent.gif",
@@ -97,15 +132,19 @@ Binary strings are not valid JSON, so BLOB columns containing binary data will b
         }
     ]
 
-
 .. _cli_json_values:
 
 Nested JSON values
 ~~~~~~~~~~~~~~~~~~
 
-If one of your columns contains JSON, by default it will be returned as an escaped string::
+If one of your columns contains JSON, by default it will be returned as an escaped string:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" | python -mjson.tool
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" | python -mjson.tool
     [
         {
             "id": 1,
@@ -114,9 +153,14 @@ If one of your columns contains JSON, by default it will be returned as an escap
         }
     ]
 
-You can use the ``--json-cols`` option to automatically detect these JSON columns and output them as nested JSON data::
+You can use the ``--json-cols`` option to automatically detect these JSON columns and output them as nested JSON data:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --json-cols | python -mjson.tool
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --json-cols | python -mjson.tool
     [
         {
             "id": 1,
@@ -137,22 +181,37 @@ You can use the ``--json-cols`` option to automatically detect these JSON column
 Returning CSV or TSV
 --------------------
 
-You can use the ``--csv`` option to return results as CSV::
+You can use the ``--csv`` option to return results as CSV:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --csv
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --csv
     id,age,name
     1,4,Cleo
     2,2,Pancakes
 
-This will default to including the column names as a header row. To exclude the headers, use ``--no-headers``::
+This will default to including the column names as a header row. To exclude the headers, use ``--no-headers``:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --csv --no-headers
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --csv --no-headers
     1,4,Cleo
     2,2,Pancakes
 
-Use ``--tsv`` instead of ``--csv`` to get back tab-separated values::
+Use ``--tsv`` instead of ``--csv`` to get back tab-separated values:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --tsv
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --tsv
     id	age	name
     1	4	Cleo
     2	2	Pancakes
@@ -162,17 +221,27 @@ Use ``--tsv`` instead of ``--csv`` to get back tab-separated values::
 Table-formatted output
 ----------------------
 
-You can use the ``--table`` option (or ``-t`` shortcut) to output query results as a table::
+You can use the ``--table`` option (or ``-t`` shortcut) to output query results as a table:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --table
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --table
       id    age  name
     ----  -----  --------
        1      4  Cleo
        2      2  Pancakes
 
-You can use the ``--fmt`` option to specify different table formats, for example ``rst`` for reStructuredText::
+You can use the ``--fmt`` option to specify different table formats, for example ``rst`` for reStructuredText:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select * from dogs" --fmt rst
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select * from dogs" --fmt rst
     ====  =====  ========
       id    age  name
     ====  =====  ========
@@ -235,22 +304,31 @@ Returning raw data, such as binary content
 
 If your table contains binary data in a ``BLOB`` you can use the ``--raw`` option to output specific columns directly to standard out.
 
-For example, to retrieve a binary image from a ``BLOB`` column and store it in a file you can use the following::
+For example, to retrieve a binary image from a ``BLOB`` column and store it in a file you can use the following:
 
-    $ sqlite-utils photos.db "select contents from photos where id=1" --raw > myphoto.jpg
+.. code-block:: bash
 
-To return the first column of each result as raw data, separated by newlines, use ``--raw-lines``::
+    sqlite-utils photos.db "select contents from photos where id=1" --raw > myphoto.jpg
 
-    $ sqlite-utils photos.db "select caption from photos" --raw-lines > captions.txt
+To return the first column of each result as raw data, separated by newlines, use ``--raw-lines``:
+
+.. code-block:: bash
+
+    sqlite-utils photos.db "select caption from photos" --raw-lines > captions.txt
 
 .. _cli_query_parameters:
 
 Using named parameters
 ----------------------
 
-You can pass named parameters to the query using ``-p``::
+You can pass named parameters to the query using ``-p``:
+
+.. code-block:: bash
+
+    sqlite-utils query dogs.db "select :num * :num2" -p num 5 -p num2 6
+
+.. code-block:: output
 
-    $ sqlite-utils query dogs.db "select :num * :num2" -p num 5 -p num2 6
     [{":num * :num2": 30}]
 
 These will be correctly quoted and escaped in the SQL query, providing a safe way to combine other values with SQL.
@@ -260,9 +338,14 @@ These will be correctly quoted and escaped in the SQL query, providing a safe wa
 UPDATE, INSERT and DELETE
 -------------------------
 
-If you execute an ``UPDATE``, ``INSERT`` or ``DELETE`` query the command will return the number of affected rows::
+If you execute an ``UPDATE``, ``INSERT`` or ``DELETE`` query the command will return the number of affected rows:
+
+.. code-block:: bash
+
+    sqlite-utils dogs.db "update dogs set age = 5 where name = 'Cleo'"
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "update dogs set age = 5 where name = 'Cleo'"
     [{"rows_affected": 1}]
 
 .. _cli_query_functions:
@@ -272,9 +355,11 @@ Defining custom SQL functions
 
 You can use the ``--functions`` option to pass a block of Python code that defines additional functions which can then be called by your SQL query.
 
-This example defines a function which extracts the domain from a URL::
+This example defines a function which extracts the domain from a URL:
 
-    $ sqlite-utils query sites.db "select url, domain(url) from urls" --functions '
+.. code-block:: bash
+
+    sqlite-utils query sites.db "select url, domain(url) from urls" --functions '
     from urllib.parse import urlparse
 
     def domain(url):
@@ -290,12 +375,14 @@ SQLite extensions
 
 You can load SQLite extension modules using the ``--load-extension`` option, see :ref:`cli_load_extension`.
 
-::
+.. code-block:: bash
+
+    sqlite-utils dogs.db "select spatialite_version()" --load-extension=spatialite
+
+.. code-block:: output
 
-    $ sqlite-utils dogs.db "select spatialite_version()" --load-extension=spatialite
     [{"spatialite_version()": "4.3.0a"}]
 
-
 .. _cli_query_attach:
 
 Attaching additional databases
@@ -305,7 +392,9 @@ SQLite supports cross-database SQL queries, which can join data from tables in m
 
 You can attach one or more additional databases using the ``--attach`` option, providing an alias to use for that database and the path to the SQLite file on disk.
 
-This example attaches the ``books.db`` database under the alias ``books`` and then runs a query that combines data from that database with the default ``dogs.db`` database::
+This example attaches the ``books.db`` database under the alias ``books`` and then runs a query that combines data from that database with the default ``dogs.db`` database:
+
+.. code-block:: bash
 
     sqlite-utils dogs.db --attach books books.db \
        'select * from sqlite_master union all select * from books.sqlite_master'
@@ -322,17 +411,33 @@ The ``sqlite-utils memory`` command works similar to ``sqlite-utils query``, but
 
 You can also pass this command CSV or JSON files which will be loaded into a temporary in-memory table, allowing you to execute SQL against that data without a separate step to first convert it to SQLite.
 
-Without any extra arguments, this command executes SQL against the in-memory database directly::
+Without any extra arguments, this command executes SQL against the in-memory database directly:
+
+.. code-block:: bash
+
+    sqlite-utils memory 'select sqlite_version()'
+
+.. code-block:: output
 
-    $ sqlite-utils memory 'select sqlite_version()'
     [{"sqlite_version()": "3.35.5"}]
 
-It takes all of the same output formatting options as :ref:`sqlite-utils query <cli_query>`: ``--csv`` and ``--csv`` and ``--table`` and ``--nl``::
+It takes all of the same output formatting options as :ref:`sqlite-utils query <cli_query>`: ``--csv`` and ``--csv`` and ``--table`` and ``--nl``:
+
+.. code-block:: bash
+
+    sqlite-utils memory 'select sqlite_version()' --csv
+
+.. code-block:: output
 
-    $ sqlite-utils memory 'select sqlite_version()' --csv             
     sqlite_version()
     3.35.5
-    $ sqlite-utils memory 'select sqlite_version()' --fmt grid
+
+.. code-block:: bash
+
+    sqlite-utils memory 'select sqlite_version()' --fmt grid
+
+.. code-block:: output
+
     +--------------------+
     | sqlite_version()   |
     +====================+
@@ -344,33 +449,46 @@ It takes all of the same output formatting options as :ref:`sqlite-utils query <
 Running queries directly against CSV or JSON
 --------------------------------------------
 
-If you have data in CSV or JSON format you can load it into an in-memory SQLite database and run queries against it directly in a single command using ``sqlite-utils memory`` like this::
+If you have data in CSV or JSON format you can load it into an in-memory SQLite database and run queries against it directly in a single command using ``sqlite-utils memory`` like this:
 
-    $ sqlite-utils memory data.csv "select * from data"
+.. code-block:: bash
 
-You can pass multiple files to the command if you want to run joins between data from different files::
+    sqlite-utils memory data.csv "select * from data"
 
-    $ sqlite-utils memory one.csv two.json "select * from one join two on one.id = two.other_id"
+You can pass multiple files to the command if you want to run joins between data from different files:
+
+.. code-block:: bash
+
+    sqlite-utils memory one.csv two.json \
+      "select * from one join two on one.id = two.other_id"
 
 If your data is JSON it should be the same format supported by the :ref:`sqlite-utils insert command <cli_inserting_data>` - so either a single JSON object (treated as a single row) or a list of JSON objects.
 
 CSV data can be comma- or tab- delimited.
 
-The in-memory tables will be named after the files without their extensions. The tool also sets up aliases for those tables (using SQL views) as ``t1``, ``t2`` and so on, or you can use the alias ``t`` to refer to the first table::
+The in-memory tables will be named after the files without their extensions. The tool also sets up aliases for those tables (using SQL views) as ``t1``, ``t2`` and so on, or you can use the alias ``t`` to refer to the first table:
 
-    $ sqlite-utils memory example.csv "select * from t"
+.. code-block:: bash
 
-If two files have the same name they will be assigned a numeric suffix::
+    sqlite-utils memory example.csv "select * from t"
 
-    $ sqlite-utils memory foo/data.csv bar/data.csv "select * from data_2"
+If two files have the same name they will be assigned a numeric suffix:
 
-To read from standard input, use either ``-`` or ``stdin`` as the filename - then use ``stdin`` or ``t`` or ``t1`` as the table name::
+.. code-block:: bash
 
-    $ cat example.csv | sqlite-utils memory - "select * from stdin"
+    sqlite-utils memory foo/data.csv bar/data.csv "select * from data_2"
 
-Incoming CSV data will be assumed to use ``utf-8``. If your data uses a different character encoding you can specify that with ``--encoding``::
+To read from standard input, use either ``-`` or ``stdin`` as the filename - then use ``stdin`` or ``t`` or ``t1`` as the table name:
 
-    $ cat example.csv | sqlite-utils memory - "select * from stdin" --encoding=latin-1
+.. code-block:: bash
+
+    cat example.csv | sqlite-utils memory - "select * from stdin"
+
+Incoming CSV data will be assumed to use ``utf-8``. If your data uses a different character encoding you can specify that with ``--encoding``:
+
+.. code-block:: bash
+
+    cat example.csv | sqlite-utils memory - "select * from stdin" --encoding=latin-1
 
 If you are joining across multiple CSV files they must all use the same encoding.
 
@@ -383,24 +501,31 @@ Explicitly specifying the format
 
 By default, ``sqlite-utils memory`` will attempt to detect the incoming data format (JSON, TSV or CSV) automatically.
 
-You can instead specify an explicit format by adding a ``:csv``, ``:tsv``, ``:json`` or ``:nl`` (for newline-delimited JSON) suffix to the filename. For example::
+You can instead specify an explicit format by adding a ``:csv``, ``:tsv``, ``:json`` or ``:nl`` (for newline-delimited JSON) suffix to the filename. For example:
 
-    $ sqlite-utils memory one.dat:csv two.dat:nl "select * from one union select * from two"
+.. code-block:: bash
+    
+    sqlite-utils memory one.dat:csv two.dat:nl \
+      "select * from one union select * from two"
 
 Here the contents of ``one.dat`` will be treated as CSV and the contents of ``two.dat`` will be treated as newline-delimited JSON.
 
-To explicitly specify the format for data piped into the tool on standard input, use ``stdin:format`` - for example::
+To explicitly specify the format for data piped into the tool on standard input, use ``stdin:format`` - for example:
 
-    $ cat one.dat | sqlite-utils memory stdin:csv "select * from stdin"
+.. code-block:: bash
+
+    cat one.dat | sqlite-utils memory stdin:csv "select * from stdin"
 
 .. _cli_memory_attach:
 
 Joining in-memory data against existing databases using \-\-attach
 ------------------------------------------------------------------
 
-The :ref:`attach option <cli_query_attach>` can be used to attach database files to the in-memory connection, enabling joins between in-memory data loaded from a file and tables in existing SQLite database files. An example::
+The :ref:`attach option <cli_query_attach>` can be used to attach database files to the in-memory connection, enabling joins between in-memory data loaded from a file and tables in existing SQLite database files. An example:
 
-    $ echo "id\n1\n3\n5" | sqlite-utils memory - --attach trees trees.db \
+.. code-block:: bash
+
+    echo "id\n1\n3\n5" | sqlite-utils memory - --attach trees trees.db \
       "select * from trees.trees where rowid in (select id from stdin)"
 
 Here the ``--attach trees trees.db`` option makes the ``trees.db`` database available with an alias of ``trees``.
@@ -414,9 +539,14 @@ The CSV data that was piped into the script is available in the ``stdin`` table,
 \-\-schema, \-\-analyze, \-\-dump and \-\-save
 ----------------------------------------------
 
-To see the in-memory database schema that would be used for a file or for multiple files, use ``--schema``::
+To see the in-memory database schema that would be used for a file or for multiple files, use ``--schema``:
+
+.. code-block:: bash
+
+    sqlite-utils memory dogs.csv --schema
+
+.. code-block:: output
 
-    % sqlite-utils memory dogs.csv --schema
     CREATE TABLE [dogs] (
         [id] INTEGER,
         [age] INTEGER,
@@ -425,9 +555,14 @@ To see the in-memory database schema that would be used for a file or for multip
     CREATE VIEW t1 AS select * from [dogs];
     CREATE VIEW t AS select * from [dogs];
 
-You can run the equivalent of the :ref:`analyze-tables <cli_analyze_tables>` command using ``--analyze``::
+You can run the equivalent of the :ref:`analyze-tables <cli_analyze_tables>` command using ``--analyze``:
+
+.. code-block:: bash
+
+    sqlite-utils memory dogs.csv --analyze
+
+.. code-block:: output
 
-    % sqlite-utils memory dogs.csv --analyze
     dogs.id: (1/3)
 
       Total rows: 2
@@ -452,9 +587,14 @@ You can run the equivalent of the :ref:`analyze-tables <cli_analyze_tables>` com
 
       Distinct values: 2
 
-You can output SQL that will both create the tables and insert the full data used to populate the in-memory database using ``--dump``::
+You can output SQL that will both create the tables and insert the full data used to populate the in-memory database using ``--dump``:
+
+.. code-block:: bash
+
+    sqlite-utils memory dogs.csv --dump
+
+.. code-block:: output
 
-    % sqlite-utils memory dogs.csv --dump
     BEGIN TRANSACTION;
     CREATE TABLE [dogs] (
         [id] INTEGER,
@@ -467,9 +607,11 @@ You can output SQL that will both create the tables and insert the full data use
     CREATE VIEW t AS select * from [dogs];
     COMMIT;
 
-Passing ``--save other.db`` will instead use that SQL to populate a new database file::
+Passing ``--save other.db`` will instead use that SQL to populate a new database file:
 
-    % sqlite-utils memory dogs.csv --save dogs.db
+.. code-block:: bash
+
+    sqlite-utils memory dogs.csv --save dogs.db
 
 These features are mainly intended as debugging tools - for much more finely grained control over how data is inserted into a SQLite database file see :ref:`cli_inserting_data` and :ref:`cli_insert_csv_tsv`.
 
@@ -478,28 +620,48 @@ These features are mainly intended as debugging tools - for much more finely gra
 Returning all rows in a table
 =============================
 
-You can return every row in a specified table using the ``rows`` command::
+You can return every row in a specified table using the ``rows`` command:
+
+.. code-block:: bash
+
+    sqlite-utils rows dogs.db dogs
+
+.. code-block:: output
 
-    $ sqlite-utils rows dogs.db dogs
     [{"id": 1, "age": 4, "name": "Cleo"},
      {"id": 2, "age": 2, "name": "Pancakes"}]
 
 This command accepts the same output options as ``query`` - so you can pass ``--nl``, ``--csv``, ``--tsv``, ``--no-headers``, ``--table`` and ``--fmt``.
 
-You can use the ``-c`` option to specify a subset of columns to return::
+You can use the ``-c`` option to specify a subset of columns to return:
+
+.. code-block:: bash
+
+    sqlite-utils rows dogs.db dogs -c age -c name
+
+.. code-block:: output
 
-    $ sqlite-utils rows dogs.db dogs -c age -c name
     [{"age": 4, "name": "Cleo"},
      {"age": 2, "name": "Pancakes"}]
 
-You can filter rows using a where clause with the ``--where`` option::
+You can filter rows using a where clause with the ``--where`` option:
+
+.. code-block:: bash
+
+    sqlite-utils rows dogs.db dogs -c name --where 'name = "Cleo"'
+
+.. code-block:: output
 
-    $ sqlite-utils rows dogs.db dogs -c name --where 'name = "Cleo"'
     [{"name": "Cleo"}]
 
-Or pass named parameters using ``--where`` in combination with ``-p``::
+Or pass named parameters using ``--where`` in combination with ``-p``:
+
+.. code-block:: bash
+
+    sqlite-utils rows dogs.db dogs -c name --where 'name = :name' -p name Cleo
+
+.. code-block:: output
 
-    $ sqlite-utils rows dogs.db dogs -c name --where 'name = :name' -p name Cleo
     [{"name": "Cleo"}]
 
 You can define a sort order using ``--order column`` or ``--order 'column desc'``.
@@ -514,42 +676,72 @@ Use ``--limit N`` to only return the first ``N`` rows. Use ``--offset N`` to ret
 Listing tables
 ==============
 
-You can list the names of tables in a database using the ``tables`` command::
+You can list the names of tables in a database using the ``tables`` command:
+
+.. code-block:: bash
+
+    sqlite-utils tables mydb.db
+
+.. code-block:: output
 
-    $ sqlite-utils tables mydb.db
     [{"table": "dogs"},
      {"table": "cats"},
      {"table": "chickens"}]
 
-You can output this list in CSV using the ``--csv`` or ``--tsv`` options::
+You can output this list in CSV using the ``--csv`` or ``--tsv`` options:
+
+.. code-block:: bash
+
+    sqlite-utils tables mydb.db --csv --no-headers
+
+.. code-block:: output
 
-    $ sqlite-utils tables mydb.db --csv --no-headers
     dogs
     cats
     chickens
 
-If you just want to see the FTS4 tables, you can use ``--fts4`` (or ``--fts5`` for FTS5 tables)::
+If you just want to see the FTS4 tables, you can use ``--fts4`` (or ``--fts5`` for FTS5 tables):
+
+.. code-block:: bash
+
+    sqlite-utils tables docs.db --fts4
+
+.. code-block:: output
 
-    $ sqlite-utils tables docs.db --fts4
     [{"table": "docs_fts"}]
 
-Use ``--counts`` to include a count of the number of rows in each table::
+Use ``--counts`` to include a count of the number of rows in each table:
+
+.. code-block:: bash
+
+    sqlite-utils tables mydb.db --counts
+
+.. code-block:: output
 
-    $ sqlite-utils tables mydb.db --counts
     [{"table": "dogs", "count": 12},
      {"table": "cats", "count": 332},
      {"table": "chickens", "count": 9}]
 
-Use ``--columns`` to include a list of columns in each table::
+Use ``--columns`` to include a list of columns in each table:
+
+.. code-block:: bash
+
+    sqlite-utils tables dogs.db --counts --columns
+
+.. code-block:: output
 
-    $ sqlite-utils tables dogs.db --counts --columns
     [{"table": "Gosh", "count": 0, "columns": ["c1", "c2", "c3"]},
      {"table": "Gosh2", "count": 0, "columns": ["c1", "c2", "c3"]},
      {"table": "dogs", "count": 2, "columns": ["id", "age", "name"]}]
 
-Use ``--schema`` to include the schema of each table::
+Use ``--schema`` to include the schema of each table:
+
+.. code-block:: bash
+
+    sqlite-utils tables dogs.db --schema --table
+
+.. code-block:: output
 
-    $ sqlite-utils tables dogs.db --schema --table
     table    schema
     -------  -----------------------------------------------
     Gosh     CREATE TABLE Gosh (c1 text, c2 text, c3 text)
@@ -569,9 +761,14 @@ The ``--nl``, ``--csv``, ``--tsv``, ``--table`` and ``--fmt`` options are also a
 Listing views
 =============
 
-The ``views`` command shows any views defined in the database::
+The ``views`` command shows any views defined in the database:
+
+.. code-block:: bash
+
+    sqlite-utils views sf-trees.db --table --counts --columns --schema
+
+.. code-block:: output
 
-    $ sqlite-utils views sf-trees.db --table --counts --columns --schema
     view         count  columns               schema
     ---------  -------  --------------------  --------------------------------------------------------------
     demo_view   189144  ['qSpecies']          CREATE VIEW demo_view AS select qSpecies from Street_Tree_List
@@ -595,9 +792,14 @@ It takes the same options as the ``tables`` command:
 Listing indexes
 ===============
 
-The ``indexes`` command lists any indexes configured for the database::
+The ``indexes`` command lists any indexes configured for the database:
+
+.. code-block:: bash
+
+    sqlite-utils indexes covid.db --table
+
+.. code-block:: output
 
-    $ sqlite-utils indexes covid.db --table
     table                             index_name                                                seqno    cid  name                 desc  coll      key
     --------------------------------  ------------------------------------------------------  -------  -----  -----------------  ------  ------  -----
     johns_hopkins_csse_daily_reports  idx_johns_hopkins_csse_daily_reports_combined_key             0     12  combined_key            0  BINARY      1
@@ -609,9 +811,11 @@ The ``indexes`` command lists any indexes configured for the database::
     ny_times_us_counties              idx_ny_times_us_counties_county                               0      1  county                  0  BINARY      1
     ny_times_us_counties              idx_ny_times_us_counties_state                                0      2  state                   0  BINARY      1
 
-It shows indexes across all tables. To see indexes for specific tables, list those after the database::
+It shows indexes across all tables. To see indexes for specific tables, list those after the database:
 
-    $ sqlite-utils indexes covid.db johns_hopkins_csse_daily_reports --table
+.. code-block:: bash
+
+    sqlite-utils indexes covid.db johns_hopkins_csse_daily_reports --table
 
 The command defaults to only showing the columns that are explicitly part of the index. To also include auxiliary columns use the ``--aux`` option - these columns will be listed with a ``key`` of ``0``.
 
@@ -625,9 +829,14 @@ The command takes the same format options as the ``tables`` and ``views`` comman
 Listing triggers
 ================
 
-The ``triggers`` command shows any triggers configured for the database::
+The ``triggers`` command shows any triggers configured for the database:
+
+.. code-block:: bash
+
+    sqlite-utils triggers global-power-plants.db --table
+
+.. code-block:: output
 
-    $ sqlite-utils triggers global-power-plants.db --table
     name             table      sql
     ---------------  ---------  -----------------------------------------------------------------
     plants_insert    plants     CREATE TRIGGER [plants_insert] AFTER INSERT ON [plants]
@@ -642,9 +851,11 @@ The ``triggers`` command shows any triggers configured for the database::
                                     );
                                 END
 
-It defaults to showing triggers for all tables. To see triggers for one or more specific tables pass their names as arguments::
+It defaults to showing triggers for all tables. To see triggers for one or more specific tables pass their names as arguments:
 
-    $ sqlite-utils triggers global-power-plants.db plants
+.. code-block:: bash
+
+    sqlite-utils triggers global-power-plants.db plants
 
 The command takes the same format options as the ``tables`` and ``views`` commands.
 
@@ -656,18 +867,24 @@ The command takes the same format options as the ``tables`` and ``views`` comman
 Showing the schema
 ==================
 
-The ``sqlite-utils schema`` command shows the full SQL schema for the database::
+The ``sqlite-utils schema`` command shows the full SQL schema for the database:
+
+.. code-block:: bash
+
+    sqlite-utils schema dogs.db
+
+.. code-block:: output
 
-    $ sqlite-utils schema dogs.db
     CREATE TABLE "dogs" (
         [id] INTEGER PRIMARY KEY,
         [name] TEXT
     );
 
-This will show the schema for every table and index in the database. To view the schema just for a specified subset of tables pass those as additional arguments::
+This will show the schema for every table and index in the database. To view the schema just for a specified subset of tables pass those as additional arguments:
 
-    $ sqlite-utils schema dogs.db dogs chickens
-    ...
+.. code-block:: bash
+
+    sqlite-utils schema dogs.db dogs chickens
 
 .. note::
     In Python: :ref:`table.schema <python_api_introspection_schema>` or :ref:`db.schema <python_api_schema>`  CLI reference: :ref:`sqlite-utils schema <cli_ref_schema>`
@@ -679,9 +896,14 @@ Analyzing tables
 
 When working with a new database it can be useful to get an idea of the shape of the data. The ``sqlite-utils analyze-tables`` command inspects specified tables (or all tables) and calculates some useful details about each of the columns in those tables.
 
-To inspect the ``tags`` table in the ``github.db`` database, run the following::
+To inspect the ``tags`` table in the ``github.db`` database, run the following:
+
+.. code-block:: bash
+
+    sqlite-utils analyze-tables github.db tags
+
+.. code-block:: output
 
-    $ sqlite-utils analyze-tables github.db tags
     tags.repo: (1/3)
 
       Total rows: 261
@@ -728,15 +950,21 @@ To inspect the ``tags`` table in the ``github.db`` database, run the following::
 
 For each column this tool displays the number of null rows, the number of blank rows (rows that contain an empty string), the number of distinct values and, for columns that are not entirely distinct, the most common and least common values.
 
-If you do not specify any tables every table in the database will be analyzed::
+If you do not specify any tables every table in the database will be analyzed:
+
+.. code-block:: bash
 
     sqlite-utils analyze-tables github.db
 
-If you wish to analyze one or more specific columns, use the ``-c`` option::
+If you wish to analyze one or more specific columns, use the ``-c`` option:
+
+.. code-block:: bash
 
     sqlite-utils analyze-tables github.db tags -c sha
 
-To show more than 10 common values, use ``--common-limit 20``.  To skip the most common or least common value analysis, use ``--no-most`` or ``--no-least``::
+To show more than 10 common values, use ``--common-limit 20``.  To skip the most common or least common value analysis, use ``--no-most`` or ``--no-least``:
+
+.. code-block:: bash
 
     sqlite-utils analyze-tables github.db tags --common-limit 20 --no-least
 
@@ -745,11 +973,15 @@ To show more than 10 common values, use ``--common-limit 20``.  To skip the most
 Saving the analyzed table details
 ---------------------------------
 
-``analyze-tables`` can take quite a while to run for large database files. You can save the results of the analysis to a database table called ``_analyze_tables_`` using the ``--save`` option::
+``analyze-tables`` can take quite a while to run for large database files. You can save the results of the analysis to a database table called ``_analyze_tables_`` using the ``--save`` option:
+
+.. code-block:: bash
 
     sqlite-utils analyze-tables github.db --save
 
-The ``_analyze_tables_`` table has the following schema::
+The ``_analyze_tables_`` table has the following schema:
+
+.. code-block:: sql
 
     CREATE TABLE [_analyze_tables_] (
         [table] TEXT,
@@ -763,7 +995,9 @@ The ``_analyze_tables_`` table has the following schema::
         PRIMARY KEY ([table], [column])
     );
 
-The ``most_common`` and ``least_common`` columns will contain nested JSON arrays of the most common and least common values that look like this::
+The ``most_common`` and ``least_common`` columns will contain nested JSON arrays of the most common and least common values that look like this:
+
+.. code-block:: json
 
     [
         ["Del Libertador, Av", 5068],
@@ -783,21 +1017,29 @@ The ``most_common`` and ``least_common`` columns will contain nested JSON arrays
 Creating an empty database
 ==========================
 
-You can create a new empty database file using the ``create-database`` command::
+You can create a new empty database file using the ``create-database`` command:
 
-    $ sqlite-utils create-database empty.db
+.. code-block:: bash
 
-To enable :ref:`cli_wal` on the newly created database add the ``--enable-wal`` option::
+    sqlite-utils create-database empty.db
 
-    $ sqlite-utils create-database empty.db --enable-wal
+To enable :ref:`cli_wal` on the newly created database add the ``--enable-wal`` option:
 
-To enable SpatiaLite metadata on a newly created database, add the ``--init-spatialite`` flag::
+.. code-block:: bash
 
-    $ sqlite-utils create-database empty.db --init-spatialite
+    sqlite-utils create-database empty.db --enable-wal
 
-That will look for SpatiaLite in a set of predictable locations. To load it from somewhere else, use the ``--load-extension`` option::
+To enable SpatiaLite metadata on a newly created database, add the ``--init-spatialite`` flag:
 
-    $ sqlite-utils create-database empty.db --init-spatialite --load-extension /path/to/spatialite.so
+.. code-block:: bash
+
+    sqlite-utils create-database empty.db --init-spatialite
+
+That will look for SpatiaLite in a set of predictable locations. To load it from somewhere else, use the ``--load-extension`` option:
+
+.. code-block:: bash
+
+    sqlite-utils create-database empty.db --init-spatialite --load-extension /path/to/spatialite.so
 
 .. _cli_inserting_data:
 
@@ -808,15 +1050,19 @@ If you have data as JSON, you can use ``sqlite-utils insert tablename`` to inser
 
 You can pass in a single JSON object or a list of JSON objects, either as a filename or piped directly to standard-in (by using ``-`` as the filename).
 
-Here's the simplest possible example::
+Here's the simplest possible example:
 
-    $ echo '{"name": "Cleo", "age": 4}' | sqlite-utils insert dogs.db dogs -
+.. code-block:: bash
+
+    echo '{"name": "Cleo", "age": 4}' | sqlite-utils insert dogs.db dogs -
 
 To specify a column as the primary key, use ``--pk=column_name``.
 
 To create a compound primary key across more than one column, use ``--pk`` multiple times.
 
-If you feed it a JSON list it will insert multiple records. For example, if ``dogs.json`` looks like this::
+If you feed it a JSON list it will insert multiple records. For example, if ``dogs.json`` looks like this:
+
+.. code-block:: json
 
     [
         {
@@ -836,17 +1082,23 @@ If you feed it a JSON list it will insert multiple records. For example, if ``do
         }
     ]
 
-You can import all three records into an automatically created ``dogs`` table and set the ``id`` column as the primary key like so::
+You can import all three records into an automatically created ``dogs`` table and set the ``id`` column as the primary key like so:
 
-    $ sqlite-utils insert dogs.db dogs dogs.json --pk=id
+.. code-block:: bash
 
-You can skip inserting any records that have a primary key that already exists using ``--ignore``::
+    sqlite-utils insert dogs.db dogs dogs.json --pk=id
 
-    $ sqlite-utils insert dogs.db dogs dogs.json --ignore
+You can skip inserting any records that have a primary key that already exists using ``--ignore``:
 
-You can delete all the existing rows in the table before inserting the new records using ``--truncate``::
+.. code-block:: bash
 
-    $ sqlite-utils insert dogs.db dogs dogs.json --truncate
+    sqlite-utils insert dogs.db dogs dogs.json --ignore
+
+You can delete all the existing rows in the table before inserting the new records using ``--truncate``:
+
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs dogs.json --truncate
 
 You can add the ``--analyze`` option to run ``ANALYZE`` against the table after the rows have been inserted.
 
@@ -855,7 +1107,9 @@ You can add the ``--analyze`` option to run ``ANALYZE`` against the table after
 Inserting binary data
 ---------------------
 
-You can insert binary data into a BLOB column by first encoding it using base64 and then structuring it like this::
+You can insert binary data into a BLOB column by first encoding it using base64 and then structuring it like this:
+
+.. code-block:: json
 
     [
         {
@@ -872,27 +1126,39 @@ You can insert binary data into a BLOB column by first encoding it using base64
 Inserting newline-delimited JSON
 --------------------------------
 
-You can also import `newline-delimited JSON <http://ndjson.org/>`__ using the ``--nl`` option::
+You can also import `newline-delimited JSON <http://ndjson.org/>`__ using the ``--nl`` option:
 
-    $ echo '{"id": 1, "name": "Cleo"}
+.. code-block:: bash
+
+    echo '{"id": 1, "name": "Cleo"}
     {"id": 2, "name": "Suna"}' | sqlite-utils insert creatures.db creatures - --nl
 
 Newline-delimited JSON consists of full JSON objects separated by newlines.
 
 If you are processing data using ``jq`` you can use the ``jq -c`` option to output valid newline-delimited JSON.
 
-Since `Datasette <https://datasette.io/>`__ can export newline-delimited JSON, you can combine the Datasette and ``sqlite-utils`` like so::
+Since `Datasette <https://datasette.io/>`__ can export newline-delimited JSON, you can combine the Datasette and ``sqlite-utils`` like so:
 
-    $ curl -L "https://latest.datasette.io/fixtures/facetable.json?_shape=array&_nl=on" \
+.. code-block:: bash
+
+    curl -L "https://latest.datasette.io/fixtures/facetable.json?_shape=array&_nl=on" \
         | sqlite-utils insert nl-demo.db facetable - --pk=id --nl
 
-You can also pipe ``sqlite-utils`` together to create a new SQLite database file containing the results of a SQL query against another database::
+You can also pipe ``sqlite-utils`` together to create a new SQLite database file containing the results of a SQL query against another database:
 
-    $ sqlite-utils sf-trees.db \
+.. code-block:: bash
+
+    sqlite-utils sf-trees.db \
         "select TreeID, qAddress, Latitude, Longitude from Street_Tree_List" --nl \
       | sqlite-utils insert saved.db trees - --nl
+    
+.. code-block:: bash
+
     # This creates saved.db with a single table called trees:
-    $ sqlite-utils saved.db "select * from trees limit 5" --csv
+    sqlite-utils saved.db "select * from trees limit 5" --csv
+
+.. code-block:: output
+
     TreeID,qAddress,Latitude,Longitude
     141565,501X Baker St,37.7759676911831,-122.441396661871
     232565,940 Elizabeth St,37.7517102172731,-122.441498017841
@@ -909,7 +1175,9 @@ Flattening nested JSON objects
 
 If your data is nested you can use the ``--flatten`` option to create columns that are derived from the nested data.
 
-Consider this example document, in a file called ``log.json``::
+Consider this example document, in a file called ``log.json``:
+
+.. code-block:: json
 
     {
         "httpRequest": {
@@ -924,7 +1192,9 @@ Consider this example document, in a file called ``log.json``::
         }
     }
 
-Inserting this into a table using ``sqlite-utils insert logs.db logs log.json`` will create a table with the following schema::
+Inserting this into a table using ``sqlite-utils insert logs.db logs log.json`` will create a table with the following schema:
+
+.. code-block:: sql
 
     CREATE TABLE [logs] (
        [httpRequest] TEXT,
@@ -932,7 +1202,9 @@ Inserting this into a table using ``sqlite-utils insert logs.db logs log.json``
        [labels] TEXT
     );
 
-With the ``--flatten`` option columns will be created using ``topkey_nextkey`` column names - so running ``sqlite-utils insert logs.db logs log.json --flatten`` will create the following schema instead::
+With the ``--flatten`` option columns will be created using ``topkey_nextkey`` column names - so running ``sqlite-utils insert logs.db logs log.json --flatten`` will create the following schema instead:
+
+.. code-block:: sql
 
     CREATE TABLE [logs] (
        [httpRequest_latency] TEXT,
@@ -948,44 +1220,61 @@ With the ``--flatten`` option columns will be created using ``topkey_nextkey`` c
 Inserting CSV or TSV data
 =========================
 
-If your data is in CSV format, you can insert it using the ``--csv`` option::
+If your data is in CSV format, you can insert it using the ``--csv`` option:
 
-    $ sqlite-utils insert dogs.db dogs dogs.csv --csv
+.. code-block:: bash
 
-For tab-delimited data, use ``--tsv``::
+    sqlite-utils insert dogs.db dogs dogs.csv --csv
 
-    $ sqlite-utils insert dogs.db dogs dogs.tsv --tsv
+For tab-delimited data, use ``--tsv``:
 
-Data is expected to be encoded as Unicode UTF-8. If your data is an another character encoding you can specify it using the ``--encoding`` option::
+.. code-block:: bash
 
-    $ sqlite-utils insert dogs.db dogs dogs.tsv --tsv --encoding=latin-1
+    sqlite-utils insert dogs.db dogs dogs.tsv --tsv
+
+Data is expected to be encoded as Unicode UTF-8. If your data is an another character encoding you can specify it using the ``--encoding`` option:
+
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs dogs.tsv --tsv --encoding=latin-1
 
 A progress bar is displayed when inserting data from a file. You can hide the progress bar using the ``--silent`` option.
 
 By default every column inserted from a CSV or TSV file will be of type ``TEXT``. To automatically detect column types - resulting in a mix of ``TEXT``, ``INTEGER`` and ``FLOAT`` columns, use the ``--detect-types`` option (or its shortcut ``-d``).
 
-For example, given a ``creatures.csv`` file containing this::
+For example, given a ``creatures.csv`` file containing this:
+
+.. code-block:: csv
 
     name,age,weight
     Cleo,6,45.5
     Dori,1,3.5
 
-The following command::
+The following command:
 
-    $ sqlite-utils insert creatures.db creatures creatures.csv --csv --detect-types
+.. code-block:: bash
 
-Will produce this schema::
+    sqlite-utils insert creatures.db creatures creatures.csv --csv --detect-types
+
+Will produce this schema:
+
+.. code-block:: bash
+
+    sqlite-utils schema creatures.db
+
+.. code-block:: sql
 
-    $ sqlite-utils schema creatures.db
     CREATE TABLE "creatures" (
        [name] TEXT,
        [age] INTEGER,
        [weight] FLOAT
     );
 
-You can set the ``SQLITE_UTILS_DETECT_TYPES`` environment variable if you want ``--detect-types`` to be the default behavior::
+You can set the ``SQLITE_UTILS_DETECT_TYPES`` environment variable if you want ``--detect-types`` to be the default behavior:
 
-    $ export SQLITE_UTILS_DETECT_TYPES=1
+.. code-block:: bash
+
+    export SQLITE_UTILS_DETECT_TYPES=1
 
 .. _cli_insert_csv_tsv_delimiter:
 
@@ -994,7 +1283,9 @@ Alternative delimiters and quote characters
 
 If your file uses a delimiter other than ``,`` or a quote character other than ``"`` you can attempt to detect delimiters or you can specify them explicitly.
 
-The ``--sniff`` option can be used to attempt to detect the delimiters::
+The ``--sniff`` option can be used to attempt to detect the delimiters:
+
+.. code-block:: bash
 
     sqlite-utils insert dogs.db dogs dogs.csv --sniff
 
@@ -1006,9 +1297,11 @@ Here's a CSV file that uses ``;`` for delimiters and the ``|`` symbol for quote
     Cleo;|Very fine; a friendly dog|
     Pancakes;A local corgi
 
-You can import that using::
+You can import that using:
 
-    $ sqlite-utils insert dogs.db dogs dogs.csv --delimiter=";" --quotechar="|"
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs dogs.csv --delimiter=";" --quotechar="|"
 
 Passing ``--delimiter``, ``--quotechar`` or ``--sniff`` implies ``--csv``, so you can omit the ``--csv`` option.
 
@@ -1028,9 +1321,11 @@ If you do this, the table will be created with column names called ``untitled_1`
 Inserting unstructured data with \-\-lines and \-\-text
 =======================================================
 
-If you have an unstructured file you can insert its contents into a table with a single ``line`` column containing each line from the file using ``--lines``. This can be useful if you intend to further analyze those lines using SQL string functions or :ref:`sqlite-utils convert <cli_convert>`::
+If you have an unstructured file you can insert its contents into a table with a single ``line`` column containing each line from the file using ``--lines``. This can be useful if you intend to further analyze those lines using SQL string functions or :ref:`sqlite-utils convert <cli_convert>`:
 
-    $ sqlite-utils insert logs.db loglines logfile.log --lines
+.. code-block:: bash
+
+    sqlite-utils insert logs.db loglines logfile.log --lines
 
 This will produce the following schema:
 
@@ -1040,9 +1335,11 @@ This will produce the following schema:
        [line] TEXT
     );
 
-You can also insert the entire contents of the file into a single column called ``text`` using ``--text``::
+You can also insert the entire contents of the file into a single column called ``text`` using ``--text``:
 
-    $ sqlite-utils insert content.db content file.txt --text
+.. code-block:: bash
+
+    sqlite-utils insert content.db content file.txt --text
 
 The schema here will be:
 
@@ -1070,9 +1367,11 @@ Given a JSON file called ``dogs.json`` containing this:
         {"id": 2, "name": "Pancakes"}
     ]
 
-The following command will insert that data and add an ``is_good`` column set to ``1`` for each dog::
+The following command will insert that data and add an ``is_good`` column set to ``1`` for each dog:
 
-    $ sqlite-utils insert dogs.db dogs dogs.json --convert 'row["is_good"] = 1'
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs dogs.json --convert 'row["is_good"] = 1'
 
 The ``--convert`` option also works with the ``--csv``, ``--tsv`` and ``--nl`` insert options.
 
@@ -1092,9 +1391,11 @@ With ``--lines``, instead of being passed a ``row`` dictionary your function wil
     INFO:     127.0.0.1:60581 - GET / HTTP/1.1 200 OK
     INFO:     127.0.0.1:60581 - GET /foo/-/static/app.css?cead5a HTTP/1.1 200 OK
 
-You could convert it into structured data like so::
+You could convert it into structured data like so:
 
-    $ sqlite-utils insert logs.db loglines access.log --convert '
+.. code-block:: bash
+
+    sqlite-utils insert logs.db loglines access.log --convert '
     type, source, _, verb, path, _, status, _ = line.split()
     return {
         "type": type,
@@ -1122,14 +1423,21 @@ With ``--text`` the entire input to the command will be made available to the fu
 
 The function can return a single dictionary which will be inserted as a single row, or it can return a list or iterator of dictionaries, each of which will be inserted.
 
-Here's how to use ``--convert`` and ``--text`` to insert one record per word in the input::
+Here's how to use ``--convert`` and ``--text`` to insert one record per word in the input:
 
-    $ echo 'A bunch of words' | sqlite-utils insert words.db words - \
+.. code-block:: bash
+
+    echo 'A bunch of words' | sqlite-utils insert words.db words - \
         --text --convert '({"word": w} for w in text.split())'
 
-The result looks like this::
+The result looks like this:
+
+.. code-block:: bash
+
+    sqlite-utils dump words.db
+
+.. code-block:: output
 
-    $ sqlite-utils dump words.db
     BEGIN TRANSACTION;
     CREATE TABLE [words] (
        [word] TEXT
@@ -1148,9 +1456,11 @@ Insert-replacing data
 
 The ``--replace`` option to ``insert`` causes any existing records with the same primary key to be replaced entirely by the new records.
 
-To replace a dog with in ID of 2 with a new record, run the following::
+To replace a dog with in ID of 2 with a new record, run the following:
 
-    $ echo '{"id": 2, "name": "Pancakes", "age": 3}' | \
+.. code-block:: bash
+
+    echo '{"id": 2, "name": "Pancakes", "age": 3}' | \
         sqlite-utils insert dogs.db dogs - --pk=id --replace
 
 .. _cli_upsert:
@@ -1162,9 +1472,11 @@ Upserting is update-or-insert. If a row exists with the specified primary key th
 
 Unlike ``insert --replace``, an upsert will ignore any column values that exist but are not present in the upsert document.
 
-For example::
+For example:
 
-    $ echo '{"id": 2, "age": 4}' | \
+.. code-block:: bash
+
+    echo '{"id": 2, "age": 4}' | \
         sqlite-utils upsert dogs.db dogs - --pk=id
 
 This will update the dog with an ID of 2 to have an age of 4, creating a new record (with a null name) if one does not exist. If a row DOES exist the name will be left as-is.
@@ -1186,7 +1498,9 @@ The command takes the database file, the SQL to be executed and the file contain
 
 The SQL query should include ``:named`` parameters that match the keys in the records.
 
-For example, given a ``chickens.csv`` CSV file containing the following::
+For example, given a ``chickens.csv`` CSV file containing the following:
+
+.. code-block:: csv
 
     id,name
     1,Blue
@@ -1196,9 +1510,11 @@ For example, given a ``chickens.csv`` CSV file containing the following::
     5,Suna
     6,Cardi
 
-You could insert those rows into a pre-created ``chickens`` table like so::
+You could insert those rows into a pre-created ``chickens`` table like so:
 
-    $ sqlite-utils bulk chickens.db \
+.. code-block:: bash
+
+    sqlite-utils bulk chickens.db \
       'insert into chickens (id, name) values (:id, :name)' \
       chickens.csv --csv
 
@@ -1213,15 +1529,21 @@ Inserting data from files
 
 The ``insert-files`` command can be used to insert the content of files, along with their metadata, into a SQLite table.
 
-Here's an example that inserts all of the GIF files in the current directory into a ``gifs.db`` database, placing the file contents in an ``images`` table::
+Here's an example that inserts all of the GIF files in the current directory into a ``gifs.db`` database, placing the file contents in an ``images`` table:
 
-    $ sqlite-utils insert-files gifs.db images *.gif
+.. code-block:: bash
 
-You can also pass one or more directories, in which case every file in those directories will be added recursively::
+    sqlite-utils insert-files gifs.db images *.gif
 
-    $ sqlite-utils insert-files gifs.db images path/to/my-gifs
+You can also pass one or more directories, in which case every file in those directories will be added recursively:
 
-By default this command will create a table with the following schema::
+.. code-block:: bash
+
+    sqlite-utils insert-files gifs.db images path/to/my-gifs
+
+By default this command will create a table with the following schema:
+
+.. code-block:: sql
 
     CREATE TABLE [images] (
         [path] TEXT PRIMARY KEY,
@@ -1231,11 +1553,15 @@ By default this command will create a table with the following schema::
 
 Content will be treated as binary by default and stored in a ``BLOB`` column. You can use the ``--text`` option to store that content in a ``TEXT`` column instead.
 
-You can customize the schema using one or more ``-c`` options. For a table schema that includes just the path, MD5 hash and last modification time of the file, you would use this::
+You can customize the schema using one or more ``-c`` options. For a table schema that includes just the path, MD5 hash and last modification time of the file, you would use this:
 
-    $ sqlite-utils insert-files gifs.db images *.gif -c path -c md5 -c mtime --pk=path
+.. code-block:: bash
 
-This will result in the following schema::
+    sqlite-utils insert-files gifs.db images *.gif -c path -c md5 -c mtime --pk=path
+
+This will result in the following schema:
+
+.. code-block:: sql
 
     CREATE TABLE [images] (
         [path] TEXT PRIMARY KEY,
@@ -1245,9 +1571,11 @@ This will result in the following schema::
 
 Note that there's no ``content`` column here at all - if you specify custom columns using ``-c`` you need to include ``-c content`` to create that column.
 
-You can change the name of one of these columns using a ``-c colname:coldef`` parameter. To rename the ``mtime`` column to ``last_modified`` you would use this::
+You can change the name of one of these columns using a ``-c colname:coldef`` parameter. To rename the ``mtime`` column to ``last_modified`` you would use this:
 
-    $ sqlite-utils insert-files gifs.db images *.gif \
+.. code-block:: bash
+
+    sqlite-utils insert-files gifs.db images *.gif \
         -c path -c md5 -c last_modified:mtime --pk=path
 
 You can pass ``--replace`` or ``--upsert`` to indicate what should happen if you try to insert a file with an existing primary key. Pass ``--alter`` to cause any missing columns to be added to the table.
@@ -1289,7 +1617,9 @@ The full list of column definitions you can use is as follows:
 ``suffix``
     The file extension - for ``file.txt.gz`` this would be ``.gz``
 
-You can insert data piped from standard input like this::
+You can insert data piped from standard input like this:
+
+.. code-block:: bash
 
     cat dog.jpg | sqlite-utils insert-files dogs.db pics - --name=dog.jpg
 
@@ -1304,27 +1634,35 @@ Converting data in columns
 
 The ``convert`` command can be used to transform the data in a specified column - for example to parse a date string into an ISO timestamp, or to split a string of tags into a JSON array.
 
-The command accepts a database, table, one or more columns and a string of Python code to be executed against the values from those columns. The following example would replace the values in the ``headline`` column in the ``articles`` table with an upper-case version::
+The command accepts a database, table, one or more columns and a string of Python code to be executed against the values from those columns. The following example would replace the values in the ``headline`` column in the ``articles`` table with an upper-case version:
 
-    $ sqlite-utils convert content.db articles headline 'value.upper()'
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles headline 'value.upper()'
 
 The Python code is passed as a string. Within that Python code the ``value`` variable will be the value of the current column.
 
-The code you provide will be compiled into a function that takes ``value`` as a single argument. If you break your function body into multiple lines the last line should be a ``return`` statement::
+The code you provide will be compiled into a function that takes ``value`` as a single argument. If you break your function body into multiple lines the last line should be a ``return`` statement:
 
-    $ sqlite-utils convert content.db articles headline '
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles headline '
     value = str(value)
     return value.upper()'
 
-Your code will be automatically wrapped in a function, but you can also define a function called ``convert(value)`` which will be called, if available::
+Your code will be automatically wrapped in a function, but you can also define a function called ``convert(value)`` which will be called, if available:
 
-    $ sqlite-utils convert content.db articles headline '
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles headline '
     def convert(value):
         return value.upper()'
 
-Use a ``CODE`` value of ``-`` to read from standard input::
+Use a ``CODE`` value of ``-`` to read from standard input:
 
-    $ cat mycode.py | sqlite-utils convert content.db articles headline -
+.. code-block:: bash
+
+    cat mycode.py | sqlite-utils convert content.db articles headline -
 
 Where ``mycode.py`` contains a fragment of Python code that looks like this:
 
@@ -1333,14 +1671,18 @@ Where ``mycode.py`` contains a fragment of Python code that looks like this:
     def convert(value):
         return value.upper()
 
-The conversion will be applied to every row in the specified table. You can limit that to just rows that match a ``WHERE`` clause using ``--where``::
+The conversion will be applied to every row in the specified table. You can limit that to just rows that match a ``WHERE`` clause using ``--where``:
 
-    $ sqlite-utils convert content.db articles headline 'value.upper()' \
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles headline 'value.upper()' \
         --where "headline like '%cat%'"
 
-You can include named parameters in your where clause and populate them using one or more ``--param`` options::
+You can include named parameters in your where clause and populate them using one or more ``--param`` options:
 
-    $ sqlite-utils convert content.db articles headline 'value.upper()' \
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles headline 'value.upper()' \
         --where "headline like :query" \
         --param query '%cat%'
 
@@ -1353,15 +1695,19 @@ By default any rows with a falsey value for the column - such as ``0`` or ``null
 Importing additional modules
 ----------------------------
 
-You can specify Python modules that should be imported and made available to your code using one or more ``--import`` options. This example uses the ``textwrap`` module to wrap the ``content`` column at 100 characters::
+You can specify Python modules that should be imported and made available to your code using one or more ``--import`` options. This example uses the ``textwrap`` module to wrap the ``content`` column at 100 characters:
 
-    $ sqlite-utils convert content.db articles content \
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles content \
         '"\n".join(textwrap.wrap(value, 100))' \
         --import=textwrap
 
-This supports nested imports as well, for example to use `ElementTree <https://docs.python.org/3/library/xml.etree.elementtree.html>`__::
+This supports nested imports as well, for example to use `ElementTree <https://docs.python.org/3/library/xml.etree.elementtree.html>`__:
 
-    $ sqlite-utils convert content.db articles content \
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles content \
         'xml.etree.ElementTree.fromstring(value).attrib["title"]' \
         --import=xml.etree.ElementTree
 
@@ -1372,10 +1718,12 @@ Using a convert() function to execute initialization
 
 In some cases you may need to execute one-off initialization code at the start of the run. You can do that by providing code that runs before defining your ``convert(value)`` function.
 
-The following example adds a new ``score`` column, then updates it to list a random number - after first seeding the random number generator to ensure that multiple runs produce the same results::
+The following example adds a new ``score`` column, then updates it to list a random number - after first seeding the random number generator to ensure that multiple runs produce the same results:
 
-    $ sqlite-utils add-column content.db articles score float --not-null-default 1.0
-    $ sqlite-utils convert content.db articles score '
+.. code-block:: bash
+
+    sqlite-utils add-column content.db articles score float --not-null-default 1.0
+    sqlite-utils convert content.db articles score '
     import random
     random.seed(10)
 
@@ -1417,14 +1765,18 @@ Various built-in recipe functions are available for common operations. These are
 ``r.parsedatetime(value, dayfirst=False, yearfirst=False, errors=None)``
   Parse a datetime and convert it to ISO datetime format: ``yyyy-mm-ddTHH:MM:SS``
 
-These recipes can be used in the code passed to ``sqlite-utils convert`` like this::
+These recipes can be used in the code passed to ``sqlite-utils convert`` like this:
 
-    $ sqlite-utils convert my.db mytable mycolumn \
+.. code-block:: bash
+
+    sqlite-utils convert my.db mytable mycolumn \
       'r.jsonsplit(value)'
 
-To use any of the documented parameters, do this::
+To use any of the documented parameters, do this:
 
-    $ sqlite-utils convert my.db mytable mycolumn \
+.. code-block:: bash
+
+    sqlite-utils convert my.db mytable mycolumn \
       'r.jsonsplit(value, delimiter=":")'
 
 .. _cli_convert_output:
@@ -1432,14 +1784,18 @@ To use any of the documented parameters, do this::
 Saving the result to a different column
 ---------------------------------------
 
-The ``--output`` and ``--output-type`` options can be used to save the result of the conversion to a separate column, which will be created if that column does not already exist::
+The ``--output`` and ``--output-type`` options can be used to save the result of the conversion to a separate column, which will be created if that column does not already exist:
 
-    $ sqlite-utils convert content.db articles headline 'value.upper()' \
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles headline 'value.upper()' \
       --output headline_upper
 
-The type of the created column defaults to ``text``, but a different column type can be specified using ``--output-type``. This example will create a new floating point column called ``id_as_a_float`` with a copy of each item's ID increased by 0.5::
+The type of the created column defaults to ``text``, but a different column type can be specified using ``--output-type``. This example will create a new floating point column called ``id_as_a_float`` with a copy of each item's ID increased by 0.5:
 
-    $ sqlite-utils convert content.db articles id 'float(value) + 0.5' \
+.. code-block:: bash
+
+    sqlite-utils convert content.db articles id 'float(value) + 0.5' \
       --output id_as_a_float \
       --output-type float
 
@@ -1454,9 +1810,11 @@ Sometimes you may wish to convert a single column into multiple derived columns.
 
 You can achieve this using the ``--multi`` option to ``sqlite-utils convert``. This option expects your Python code to return a Python dictionary: new columns well be created and populated for each of the keys in that dictionary.
 
-For the ``latitude,longitude`` example you would use the following::
+For the ``latitude,longitude`` example you would use the following:
 
-    $ sqlite-utils convert demo.db places location \
+.. code-block:: bash
+
+    sqlite-utils convert demo.db places location \
     'bits = value.split(",")
     return {
       "latitude": float(bits[0]),
@@ -1480,9 +1838,11 @@ The code function can also return ``None``, in which case its output will be ign
 Creating tables
 ===============
 
-Most of the time creating tables by inserting example data is the quickest approach. If you need to create an empty table in advance of inserting data you can do so using the ``create-table`` command::
+Most of the time creating tables by inserting example data is the quickest approach. If you need to create an empty table in advance of inserting data you can do so using the ``create-table`` command:
 
-    $ sqlite-utils create-table mydb.db mytable id integer name text --pk=id
+.. code-block:: bash
+
+    sqlite-utils create-table mydb.db mytable id integer name text --pk=id
 
 This will create a table called ``mytable`` with two columns - an integer ``id`` column and a text ``name`` column. It will set the ``id`` column to be the primary key.
 
@@ -1490,9 +1850,9 @@ You can pass as many column-name column-type pairs as you like. Valid types are
 
 You can specify columns that should be NOT NULL using ``--not-null colname``. You can specify default values for columns using ``--default colname defaultvalue``.
 
-::
+.. code-block:: bash
 
-    $ sqlite-utils create-table mydb.db mytable \
+    sqlite-utils create-table mydb.db mytable \
         id integer \
         name text \
         age integer \
@@ -1501,8 +1861,10 @@ You can specify columns that should be NOT NULL using ``--not-null colname``. Yo
         --not-null age \
         --default is_good 1 \
         --pk=id
+    sqlite-utils tables mydb.db --schema -t
+
+.. code-block:: output
 
-    $ sqlite-utils tables mydb.db --schema -t
     table    schema
     -------  --------------------------------
     mytable  CREATE TABLE [mytable] (
@@ -1512,21 +1874,26 @@ You can specify columns that should be NOT NULL using ``--not-null colname``. Yo
                 [is_good] INTEGER DEFAULT '1'
             )
 
-You can specify foreign key relationships between the tables you are creating using ``--fk colname othertable othercolumn``::
+You can specify foreign key relationships between the tables you are creating using ``--fk colname othertable othercolumn``:
 
-    $ sqlite-utils create-table books.db authors \
+.. code-block:: bash
+
+    sqlite-utils create-table books.db authors \
         id integer \
         name text \
         --pk=id
 
-    $ sqlite-utils create-table books.db books \
+    sqlite-utils create-table books.db books \
         id integer \
         title text \
         author_id integer \
         --pk=id \
         --fk author_id authors id
 
-    $ sqlite-utils tables books.db --schema -t
+    sqlite-utils tables books.db --schema -t
+
+.. code-block:: output
+
     table    schema
     -------  -------------------------------------------------
     authors  CREATE TABLE [authors] (
@@ -1548,18 +1915,22 @@ You can also pass ``--transform`` to transform the existing table to match the n
 Duplicating tables
 ==================
 
-The ``duplicate`` command duplicates a table - creating a new table with the same schema and a copy of all of the rows::
+The ``duplicate`` command duplicates a table - creating a new table with the same schema and a copy of all of the rows:
 
-    $ sqlite-utils duplicate books.db authors authors_copy
+.. code-block:: bash
+
+    sqlite-utils duplicate books.db authors authors_copy
 
 .. _cli_drop_table:
 
 Dropping tables
 ===============
 
-You can drop a table using the ``drop-table`` command::
+You can drop a table using the ``drop-table`` command:
 
-    $ sqlite-utils drop-table mydb.db mytable
+.. code-block:: bash
+
+    sqlite-utils drop-table mydb.db mytable
 
 Use ``--ignore`` to ignore the error if the table does not exist.
 
@@ -1570,9 +1941,9 @@ Transforming tables
 
 The ``transform`` command allows you to apply complex transformations to a table that cannot be implemented using a regular SQLite ``ALTER TABLE`` command. See :ref:`python_api_transform` for details of how this works.
 
-::
+.. code-block:: bash
 
-    $ sqlite-utils transform mydb.db mytable \
+    sqlite-utils transform mydb.db mytable \
         --drop column1 \
         --rename column2 column_renamed
 
@@ -1611,9 +1982,11 @@ Every option for this table (with the exception of ``--pk-none``) can be specifi
 ``--drop-foreign-key column``
     Drop the specified foreign key.
 
-If you want to see the SQL that will be executed to make the change without actually executing it, add the ``--sql`` flag. For example::
+If you want to see the SQL that will be executed to make the change without actually executing it, add the ``--sql`` flag. For example:
 
-    $ sqlite-utils transform fixtures.db roadside_attractions \
+.. code-block:: bash
+
+    sqlite-utils transform fixtures.db roadside_attractions \
         --rename pk id \
         --default name Untitled \
         --column-order id \
@@ -1621,6 +1994,9 @@ If you want to see the SQL that will be executed to make the change without actu
         --column-order latitude \
         --drop address \
         --sql
+
+.. code-block:: sql
+
     CREATE TABLE [roadside_attractions_new_4033a60276b9] (
        [id] INTEGER PRIMARY KEY,
        [longitude] FLOAT,
@@ -1637,34 +2013,68 @@ If you want to see the SQL that will be executed to make the change without actu
 Adding a primary key to a rowid table
 -------------------------------------
 
-SQLite tables that are created without an explicit primary key are created as `rowid tables <https://www.sqlite.org/rowidtable.html>`__. They still have a numeric primary key which is available in the ``rowid`` column, but that column is not included in the output of ``select *``. Here's an example::
+SQLite tables that are created without an explicit primary key are created as `rowid tables <https://www.sqlite.org/rowidtable.html>`__. They still have a numeric primary key which is available in the ``rowid`` column, but that column is not included in the output of ``select *``. Here's an example:
 
-    % echo '[{"name": "Azi"}, {"name": "Suna"}]' | \
+.. code-block:: bash
+
+    echo '[{"name": "Azi"}, {"name": "Suna"}]' | \
         sqlite-utils insert chickens.db chickens -
-    % sqlite-utils schema chickens.db
+    sqlite-utils schema chickens.db
+
+.. code-block:: output
+
     CREATE TABLE [chickens] (
        [name] TEXT
     );
-    % sqlite-utils chickens.db 'select * from chickens'
+
+.. code-block:: bash
+
+    sqlite-utils chickens.db 'select * from chickens'
+
+.. code-block:: output
+
     [{"name": "Azi"},
      {"name": "Suna"}]
-    % sqlite-utils chickens.db 'select rowid, * from chickens'
+
+.. code-block:: bash
+
+    sqlite-utils chickens.db 'select rowid, * from chickens'
+
+.. code-block:: output
+
     [{"rowid": 1, "name": "Azi"},
      {"rowid": 2, "name": "Suna"}]
 
-You can use ``sqlite-utils transform ... --pk id`` to add a primary key column called ``id`` to the table. The primary key will be created as an ``INTEGER PRIMARY KEY`` and the existing ``rowid`` values will be copied across to it. It will automatically increment as new rows are added to the table::
+You can use ``sqlite-utils transform ... --pk id`` to add a primary key column called ``id`` to the table. The primary key will be created as an ``INTEGER PRIMARY KEY`` and the existing ``rowid`` values will be copied across to it. It will automatically increment as new rows are added to the table:
+
+.. code-block:: bash
+
+    sqlite-utils transform chickens.db chickens --pk id
+    sqlite-utils schema chickens.db
+
+.. code-block:: output
 
-    % sqlite-utils transform chickens.db chickens --pk id
-    % sqlite-utils schema chickens.db
     CREATE TABLE "chickens" (
        [id] INTEGER PRIMARY KEY,
        [name] TEXT
     );
-    % sqlite-utils chickens.db 'select * from chickens'
+
+.. code-block:: bash
+
+    sqlite-utils chickens.db 'select * from chickens'
+
+.. code-block:: output
+
     [{"id": 1, "name": "Azi"},
      {"id": 2, "name": "Suna"}]
-    % echo '{"name": "Cardi"}' | sqlite-utils insert chickens.db chickens -
-    % sqlite-utils chickens.db 'select * from chickens'
+
+.. code-block:: bash
+
+    echo '{"name": "Cardi"}' | sqlite-utils insert chickens.db chickens -
+    sqlite-utils chickens.db 'select * from chickens'
+
+.. code-block:: output
+
     [{"id": 1, "name": "Azi"},
      {"id": 2, "name": "Suna"},
      {"id": 3, "name": "Cardi"}]
@@ -1678,9 +2088,11 @@ The ``sqlite-utils extract`` command can be used to extract specified columns in
 
 Take a look at the Python API documentation for :ref:`python_api_extract` for a detailed description of how this works, including examples of table schemas before and after running an extraction operation.
 
-The command takes a database, table and one or more columns that should be extracted. To extract the ``species`` column from the ``trees`` table you would run::
+The command takes a database, table and one or more columns that should be extracted. To extract the ``species`` column from the ``trees`` table you would run:
 
-    $ sqlite-utils extract my.db trees species
+.. code-block:: bash
+
+    sqlite-utils extract my.db trees species
 
 This would produce the following schema:
 
@@ -1713,7 +2125,9 @@ The command takes the following options:
 ``--silent``
     Don't display the progress bar.
 
-Here's a more complex example that makes use of these options. It converts `this CSV file <https://github.com/wri/global-power-plant-database/blob/232a666653e14d803ab02717efc01cdd437e7601/output_database/global_power_plant_database.csv>`__ full of global power plants into SQLite, then extracts the ``country`` and ``country_long`` columns into a separate ``countries`` table::
+Here's a more complex example that makes use of these options. It converts `this CSV file <https://github.com/wri/global-power-plant-database/blob/232a666653e14d803ab02717efc01cdd437e7601/output_database/global_power_plant_database.csv>`__ full of global power plants into SQLite, then extracts the ``country`` and ``country_long`` columns into a separate ``countries`` table:
+
+.. code-block:: bash
 
     wget 'https://github.com/wri/global-power-plant-database/blob/232a6666/output_database/global_power_plant_database.csv?raw=true'
     sqlite-utils insert global.db power_plants \
@@ -1768,11 +2182,15 @@ After running the above, the command ``sqlite-utils schema global.db`` reveals t
 Creating views
 ==============
 
-You can create a view using the ``create-view`` command::
+You can create a view using the ``create-view`` command:
 
-    $ sqlite-utils create-view mydb.db version "select sqlite_version()"
+.. code-block:: bash
+
+    sqlite-utils create-view mydb.db version "select sqlite_version()"
+    sqlite-utils mydb.db "select * from version"
+
+.. code-block:: output
 
-    $ sqlite-utils mydb.db "select * from version"
     [{"sqlite_version()": "3.31.1"}]
 
 Use ``--replace`` to replace an existing view of the same name, and ``--ignore`` to do nothing if a view already exists.
@@ -1782,9 +2200,11 @@ Use ``--replace`` to replace an existing view of the same name, and ``--ignore``
 Dropping views
 ==============
 
-You can drop a view using the ``drop-view`` command::
+You can drop a view using the ``drop-view`` command:
 
-    $ sqlite-utils drop-view myview
+.. code-block:: bash
+
+    sqlite-utils drop-view myview
 
 Use ``--ignore`` to ignore the error if the view does not exist.
 
@@ -1793,34 +2213,44 @@ Use ``--ignore`` to ignore the error if the view does not exist.
 Adding columns
 ==============
 
-You can add a column using the ``add-column`` command::
+You can add a column using the ``add-column`` command:
 
-    $ sqlite-utils add-column mydb.db mytable nameofcolumn text
+.. code-block:: bash
+
+    sqlite-utils add-column mydb.db mytable nameofcolumn text
 
 The last argument here is the type of the column to be created. You can use one of ``text``, ``integer``, ``float`` or ``blob``. If you leave it off, ``text`` will be used.
 
-You can add a column that is a foreign key reference to another table using the ``--fk`` option::
+You can add a column that is a foreign key reference to another table using the ``--fk`` option:
 
-    $ sqlite-utils add-column mydb.db dogs species_id --fk species
+.. code-block:: bash
+
+    sqlite-utils add-column mydb.db dogs species_id --fk species
 
 This will automatically detect the name of the primary key on the species table and use that (and its type) for the new column.
 
-You can explicitly specify the column you wish to reference using ``--fk-col``::
+You can explicitly specify the column you wish to reference using ``--fk-col``:
 
-    $ sqlite-utils add-column mydb.db dogs species_id --fk species --fk-col ref
+.. code-block:: bash
 
-You can set a ``NOT NULL DEFAULT 'x'`` constraint on the new column using ``--not-null-default``::
+    sqlite-utils add-column mydb.db dogs species_id --fk species --fk-col ref
 
-    $ sqlite-utils add-column mydb.db dogs friends_count integer --not-null-default 0
+You can set a ``NOT NULL DEFAULT 'x'`` constraint on the new column using ``--not-null-default``:
+
+.. code-block:: bash
+
+    sqlite-utils add-column mydb.db dogs friends_count integer --not-null-default 0
 
 .. _cli_add_column_alter:
 
 Adding columns automatically on insert/update
 =============================================
 
-You can use the ``--alter`` option to automatically add new columns if the data you are inserting or upserting is of a different shape::
+You can use the ``--alter`` option to automatically add new columns if the data you are inserting or upserting is of a different shape:
 
-    $ sqlite-utils insert dogs.db dogs new-dogs.json --pk=id --alter
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs new-dogs.json --pk=id --alter
 
 .. _cli_add_foreign_key:
 
@@ -1829,17 +2259,23 @@ Adding foreign key constraints
 
 The ``add-foreign-key`` command can be used to add new foreign key references to an existing table - something which SQLite's ``ALTER TABLE`` command does not support.
 
-To add a foreign key constraint pointing the ``books.author_id`` column to ``authors.id`` in another table, do this::
+To add a foreign key constraint pointing the ``books.author_id`` column to ``authors.id`` in another table, do this:
 
-    $ sqlite-utils add-foreign-key books.db books author_id authors id
+.. code-block:: bash
 
-If you omit the other table and other column references ``sqlite-utils`` will attempt to guess them - so the above example could instead look like this::
+    sqlite-utils add-foreign-key books.db books author_id authors id
 
-    $ sqlite-utils add-foreign-key books.db books author_id
+If you omit the other table and other column references ``sqlite-utils`` will attempt to guess them - so the above example could instead look like this:
 
-Add ``--ignore`` to ignore an existing foreign key (as opposed to returning an error)::
+.. code-block:: bash
 
-    $ sqlite-utils add-foreign-key books.db books author_id --ignore
+    sqlite-utils add-foreign-key books.db books author_id
+
+Add ``--ignore`` to ignore an existing foreign key (as opposed to returning an error):
+
+.. code-block:: bash
+
+    sqlite-utils add-foreign-key books.db books author_id --ignore
 
 See :ref:`python_api_add_foreign_key` in the Python API documentation for further details, including how the automatic table guessing mechanism works.
 
@@ -1848,9 +2284,11 @@ See :ref:`python_api_add_foreign_key` in the Python API documentation for furthe
 Adding multiple foreign keys at once
 ------------------------------------
 
-Adding a foreign key requires a ``VACUUM``. On large databases this can be an expensive operation, so if you are adding multiple foreign keys you can combine them into one operation (and hence one ``VACUUM``) using ``add-foreign-keys``::
+Adding a foreign key requires a ``VACUUM``. On large databases this can be an expensive operation, so if you are adding multiple foreign keys you can combine them into one operation (and hence one ``VACUUM``) using ``add-foreign-keys``:
 
-    $ sqlite-utils add-foreign-keys books.db \
+.. code-block:: bash
+
+    sqlite-utils add-foreign-keys books.db \
         books author_id authors id \
         authors country_id countries id
 
@@ -1861,18 +2299,22 @@ When you are using this command each foreign key needs to be defined in full, as
 Adding indexes for all foreign keys
 -----------------------------------
 
-If you want to ensure that every foreign key column in your database has a corresponding index, you can do so like this::
+If you want to ensure that every foreign key column in your database has a corresponding index, you can do so like this:
 
-    $ sqlite-utils index-foreign-keys books.db
+.. code-block:: bash
+
+    sqlite-utils index-foreign-keys books.db
 
 .. _cli_defaults_not_null:
 
 Setting defaults and not null constraints
 =========================================
 
-You can use the ``--not-null`` and ``--default`` options (to both ``insert`` and ``upsert``) to specify columns that should be ``NOT NULL`` or to set database defaults for one or more specific columns::
+You can use the ``--not-null`` and ``--default`` options (to both ``insert`` and ``upsert``) to specify columns that should be ``NOT NULL`` or to set database defaults for one or more specific columns:
 
-    $ sqlite-utils insert dogs.db dogs_with_scores dogs-with-scores.json \
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs_with_scores dogs-with-scores.json \
         --not-null=age \
         --not-null=name \
         --default age 2 \
@@ -1883,9 +2325,11 @@ You can use the ``--not-null`` and ``--default`` options (to both ``insert`` and
 Creating indexes
 ================
 
-You can add an index to an existing table using the ``create-index`` command::
+You can add an index to an existing table using the ``create-index`` command:
 
-    $ sqlite-utils create-index mydb.db mytable col1 [col2...]
+.. code-block:: bash
+
+    sqlite-utils create-index mydb.db mytable col1 [col2...]
 
 This can be used to create indexes against a single column or multiple columns.
 
@@ -1895,9 +2339,11 @@ Use the ``--unique`` option to create a unique index.
 
 Use ``--if-not-exists`` to avoid attempting to create the index if one with that name already exists.
 
-To add an index on a column in descending order, prefix the column with a hyphen. Since this can be confused for a command-line option you need to construct that like this::
+To add an index on a column in descending order, prefix the column with a hyphen. Since this can be confused for a command-line option you need to construct that like this:
 
-    $ sqlite-utils create-index mydb.db mytable -- col1 -col2 col3
+.. code-block:: bash
+
+    sqlite-utils create-index mydb.db mytable -- col1 -col2 col3
 
 This will create an index on that table on ``(col1, col2 desc, col3)``.
 
@@ -1910,67 +2356,94 @@ Add the ``--analyze`` option to run ``ANALYZE`` against the index after it has b
 Configuring full-text search
 ============================
 
-You can enable SQLite full-text search on a table and a set of columns like this::
+You can enable SQLite full-text search on a table and a set of columns like this:
 
-    $ sqlite-utils enable-fts mydb.db documents title summary
+.. code-block:: bash
 
-This will use SQLite's FTS5 module by default. Use ``--fts4`` if you want to use FTS4::
+    sqlite-utils enable-fts mydb.db documents title summary
 
-    $ sqlite-utils enable-fts mydb.db documents title summary --fts4
+This will use SQLite's FTS5 module by default. Use ``--fts4`` if you want to use FTS4:
 
-The ``enable-fts`` command will populate the new index with all existing documents. If you later add more documents you will need to use ``populate-fts`` to cause them to be indexed as well::
+.. code-block:: bash
 
-    $ sqlite-utils populate-fts mydb.db documents title summary
+    sqlite-utils enable-fts mydb.db documents title summary --fts4
 
-A better solution here is to use database triggers. You can set up database triggers to automatically update the full-text index using the ``--create-triggers`` option when you first run ``enable-fts``::
+The ``enable-fts`` command will populate the new index with all existing documents. If you later add more documents you will need to use ``populate-fts`` to cause them to be indexed as well:
 
-    $ sqlite-utils enable-fts mydb.db documents title summary --create-triggers
+.. code-block:: bash
 
-To set a custom FTS tokenizer, e.g. to enable Porter stemming, use ``--tokenize=``::
+    sqlite-utils populate-fts mydb.db documents title summary
 
-    $ sqlite-utils populate-fts mydb.db documents title summary --tokenize=porter
+A better solution here is to use database triggers. You can set up database triggers to automatically update the full-text index using the ``--create-triggers`` option when you first run ``enable-fts``:
 
-To remove the FTS tables and triggers you created, use ``disable-fts``::
+.. code-block:: bash
 
-    $ sqlite-utils disable-fts mydb.db documents
+    sqlite-utils enable-fts mydb.db documents title summary --create-triggers
 
-To rebuild one or more FTS tables (see :ref:`python_api_fts_rebuild`), use ``rebuild-fts``::
+To set a custom FTS tokenizer, e.g. to enable Porter stemming, use ``--tokenize=``:
 
-    $ sqlite-utils rebuild-fts mydb.db documents
+.. code-block:: bash
 
-You can rebuild every FTS table by running ``rebuild-fts`` without passing any table names::
+    sqlite-utils populate-fts mydb.db documents title summary --tokenize=porter
 
-    $ sqlite-utils rebuild-fts mydb.db
+To remove the FTS tables and triggers you created, use ``disable-fts``:
+
+.. code-block:: bash
+
+    sqlite-utils disable-fts mydb.db documents
+
+To rebuild one or more FTS tables (see :ref:`python_api_fts_rebuild`), use ``rebuild-fts``:
+
+.. code-block:: bash
+
+    sqlite-utils rebuild-fts mydb.db documents
+
+You can rebuild every FTS table by running ``rebuild-fts`` without passing any table names:
+
+.. code-block:: bash
+
+    sqlite-utils rebuild-fts mydb.db
 
 .. _cli_search:
 
 Executing searches
 ==================
 
-Once you have configured full-text search for a table, you can search it using ``sqlite-utils search``::
+Once you have configured full-text search for a table, you can search it using ``sqlite-utils search``:
 
-    $ sqlite-utils search mydb.db documents searchterm
+.. code-block:: bash
+
+    sqlite-utils search mydb.db documents searchterm
 
 This command accepts the same output options as ``sqlite-utils query``: ``--table``, ``--csv``, ``--tsv``, ``--nl`` etc.
 
-By default it shows the most relevant matches first. You can specify a different sort order using the ``-o`` option, which can take a column or a column followed by ``desc``::
+By default it shows the most relevant matches first. You can specify a different sort order using the ``-o`` option, which can take a column or a column followed by ``desc``:
+
+.. code-block:: bash
 
     # Sort by rowid
-    $ sqlite-utils search mydb.db documents searchterm -o rowid
+    sqlite-utils search mydb.db documents searchterm -o rowid
     # Sort by created in descending order
-    $ sqlite-utils search mydb.db documents searchterm -o 'created desc'
+    sqlite-utils search mydb.db documents searchterm -o 'created desc'
 
 SQLite `advanced search syntax <https://www.sqlite.org/fts5.html#full_text_query_syntax>`__ is enabled by default. To run a search with automatic quoting applied to the terms to avoid them being potentially interpreted as advanced search syntax use the ``--quote`` option.
 
-You can specify a subset of columns to be returned using the ``-c`` option one or more times::
+You can specify a subset of columns to be returned using the ``-c`` option one or more times:
 
-    $ sqlite-utils search mydb.db documents searchterm -c title -c created
+.. code-block:: bash
+
+    sqlite-utils search mydb.db documents searchterm -c title -c created
 
 By default all search results will be returned. You can use ``--limit 20`` to return just the first 20 results.
 
-Use the ``--sql`` option to output the SQL that would be executed, rather than running the query::
+Use the ``--sql`` option to output the SQL that would be executed, rather than running the query:
+
+.. code-block:: bash
+
+    sqlite-utils search mydb.db documents searchterm --sql
+
+.. code-block:: output
 
-    $ sqlite-utils search mydb.db documents searchterm --sql                  
     with original as (
         select
             rowid,
@@ -1996,17 +2469,19 @@ Enabling cached counts
 
 The ``sqlite-utils enable-counts`` command can be used to configure these triggers, either for every table in the database or for specific tables.
 
-::
+.. code-block:: bash
 
     # Configure triggers for every table in the database
-    $ sqlite-utils enable-counts mydb.db
+    sqlite-utils enable-counts mydb.db
 
     # Configure triggers just for specific tables
-    $ sqlite-utils enable-counts mydb.db table1 table2
+    sqlite-utils enable-counts mydb.db table1 table2
 
-If the ``_counts`` table ever becomes out-of-sync with the actual table counts you can repair it using the ``reset-counts`` command::
+If the ``_counts`` table ever becomes out-of-sync with the actual table counts you can repair it using the ``reset-counts`` command:
 
-    $ sqlite-utils reset-counts mydb.db
+.. code-block:: bash
+
+    sqlite-utils reset-counts mydb.db
 
 .. _cli_analyze:
 
@@ -2017,13 +2492,17 @@ The `SQLite ANALYZE command <https://www.sqlite.org/lang_analyze.html>`__ builds
 
 You should run ``ANALYZE`` if your database is large and you do not think your indexes are being efficiently used.
 
-To run ``ANALYZE`` against every index in a database, use this::
+To run ``ANALYZE`` against every index in a database, use this:
 
-    $ sqlite-utils analyze mydb.db
+.. code-block:: bash
 
-You can run it against specific tables, or against specific named indexes, by passing them as optional arguments::
+    sqlite-utils analyze mydb.db
 
-    $ sqlite-utils analyze mydb.db mytable idx_mytable_name
+You can run it against specific tables, or against specific named indexes, by passing them as optional arguments:
+
+.. code-block:: bash
+
+    sqlite-utils analyze mydb.db mytable idx_mytable_name
 
 You can also run ``ANALYZE`` as part of another command using the ``--analyze`` option. This is supported by the ``create-index``, ``insert`` and ``upsert`` commands.
 
@@ -2032,9 +2511,11 @@ You can also run ``ANALYZE`` as part of another command using the ``--analyze``
 Vacuum
 ======
 
-You can run VACUUM to optimize your database like so::
+You can run VACUUM to optimize your database like so:
 
-    $ sqlite-utils vacuum mydb.db
+.. code-block:: bash
+
+    sqlite-utils vacuum mydb.db
 
 .. _cli_optimize:
 
@@ -2045,32 +2526,36 @@ The optimize command can dramatically reduce the size of your database if you ar
 
 If you just want to run OPTIMIZE without the VACUUM, use the ``--no-vacuum`` flag.
 
-::
+.. code-block:: bash
 
     # Optimize all FTS tables and then VACUUM
-    $ sqlite-utils optimize mydb.db
+    sqlite-utils optimize mydb.db
 
     # Optimize but skip the VACUUM
-    $ sqlite-utils optimize --no-vacuum mydb.db
+    sqlite-utils optimize --no-vacuum mydb.db
 
 To optimize specific tables rather than every FTS table, pass those tables as extra arguments:
 
-::
+.. code-block:: bash
 
-    $ sqlite-utils optimize mydb.db table_1 table_2
+    sqlite-utils optimize mydb.db table_1 table_2
 
 .. _cli_wal:
 
 WAL mode
 ========
 
-You can enable `Write-Ahead Logging <https://www.sqlite.org/wal.html>`__ for a database file using the ``enable-wal`` command::
+You can enable `Write-Ahead Logging <https://www.sqlite.org/wal.html>`__ for a database file using the ``enable-wal`` command:
 
-    $ sqlite-utils enable-wal mydb.db
+.. code-block:: bash
 
-You can disable WAL mode using ``disable-wal``::
+    sqlite-utils enable-wal mydb.db
 
-    $ sqlite-utils disable-wal mydb.db
+You can disable WAL mode using ``disable-wal``:
+
+.. code-block:: bash
+
+    sqlite-utils disable-wal mydb.db
 
 Both of these commands accept one or more database files as arguments.
 
@@ -2079,9 +2564,11 @@ Both of these commands accept one or more database files as arguments.
 Dumping the database to SQL
 ===========================
 
-The ``dump`` command outputs a SQL dump of the schema and full contents of the specified database file::
+The ``dump`` command outputs a SQL dump of the schema and full contents of the specified database file:
 
-    $ sqlite-utils dump mydb.db
+.. code-block:: bash
+
+    sqlite-utils dump mydb.db
     BEGIN TRANSACTION;
     CREATE TABLE ...
     ...
@@ -2096,9 +2583,11 @@ Many of these commands have the ability to load additional SQLite extensions usi
 
 This option can be applied multiple times to load multiple extensions.
 
-Since `SpatiaLite <https://www.gaia-gis.it/fossil/libspatialite/index>`__ is commonly used with SQLite, the value ``spatialite`` is special: it will search for SpatiaLite in the most common installation locations, saving you from needing to remember exactly where that module is located::
+Since `SpatiaLite <https://www.gaia-gis.it/fossil/libspatialite/index>`__ is commonly used with SQLite, the value ``spatialite`` is special: it will search for SpatiaLite in the most common installation locations, saving you from needing to remember exactly where that module is located:
 
-    $ sqlite-utils memory "select spatialite_version()" --load-extension=spatialite
+.. code-block:: bash
+
+    sqlite-utils memory "select spatialite_version()" --load-extension=spatialite
     [{"spatialite_version()": "4.3.0a"}]
 
 .. _cli_spatialite:
@@ -2108,9 +2597,11 @@ SpatiaLite helpers
 
 `SpatiaLite <https://www.gaia-gis.it/fossil/libspatialite/home>`_ adds geographic capability to SQLite (similar to how PostGIS builds on PostgreSQL). The `SpatiaLite cookbook <http://www.gaia-gis.it/gaia-sins/spatialite-cookbook-5/index.html>`__ is a good resource for learning what's possible with it.
 
-You can convert an existing table to a geographic table by adding a geometry column, use the ``sqlite-utils add-geometry-column`` command::
+You can convert an existing table to a geographic table by adding a geometry column, use the ``sqlite-utils add-geometry-column`` command:
 
-    $ sqlite-utils add-geometry-column spatial.db locations geometry --type POLYGON --srid 4326
+.. code-block:: bash
+
+    sqlite-utils add-geometry-column spatial.db locations geometry --type POLYGON --srid 4326
 
 The table (``locations`` in the example above) must already exist before adding a geometry column. Use ``sqlite-utils create-table`` first, then ``add-geometry-column``.
 
@@ -2132,9 +2623,11 @@ Eight (case-insensitive) types are allowed:
 Adding spatial indexes
 ----------------------
 
-Once you have a geometry column, you can speed up bounding box queries by adding a spatial index::
+Once you have a geometry column, you can speed up bounding box queries by adding a spatial index:
 
-    $ sqlite-utils create-spatial-index spatial.db locations geometry
+.. code-block:: bash
+
+    sqlite-utils create-spatial-index spatial.db locations geometry
 
 See this `SpatiaLite Cookbook recipe <http://www.gaia-gis.it/gaia-sins/spatialite-cookbook-5/cookbook_topics.03.html#topic_Wonderful_RTree_Spatial_Index>`__ for examples of how to use a spatial index.
 
@@ -2147,9 +2640,9 @@ The :ref:`convert command <cli_convert>` and the :ref:`insert -\\-convert <cli_i
 
 You can install packages from PyPI directly into the correct environment using ``sqlite-utils install <package>``. This is a wrapper around ``pip install``.
 
-::
+.. code-block:: bash
 
-    $ sqlite-utils install beautifulsoup4
+    sqlite-utils install beautifulsoup4
 
 Use ``-U`` to upgrade an existing package.
 
@@ -2158,9 +2651,11 @@ Use ``-U`` to upgrade an existing package.
 Uninstalling packages
 =====================
 
-You can uninstall packages that were installed using ``sqlite-utils install`` with ``sqlite-utils uninstall <package>``::
+You can uninstall packages that were installed using ``sqlite-utils install`` with ``sqlite-utils uninstall <package>``:
 
-    $ sqlite-utils uninstall beautifulsoup4
+.. code-block:: bash
+
+    sqlite-utils uninstall beautifulsoup4
 
 Use ``-y`` to skip the request for confirmation.
 
@@ -2173,11 +2668,15 @@ A TUI is a "text user interface" (or "terminal user interface") - a keyboard and
 
 ``sqlite-utils`` has experimental support for a TUI for building command-line invocations, built on top of the `Trogon <https://github.com/Textualize/trogon/>`__ TUI library.
 
-To enable this feature you will need to install the ``trogon`` dependency. You can do that like so::
+To enable this feature you will need to install the ``trogon`` dependency. You can do that like so:
+
+.. code-block:: bash
 
     sqite-utils install trogon
 
-Once installed, running the ``sqlite-utils tui`` command will launch the TUI interface::
+Once installed, running the ``sqlite-utils tui`` command will launch the TUI interface:
+
+.. code-block:: bash
 
     sqlite-utils tui