From 6bb1248afa55ac7619926e2be1740779da85fbc0 Mon Sep 17 00:00:00 2001
From: fly1d <309400591+fly1d@users.noreply.github.com>
Date: Wed, 26 Aug 2026 20:19:02 +0800
Subject: [PATCH] docs: keep CLI flags literal in Python API references

Refs #493; follow-up to #844.

OpenAI Codex assisted with implementation and verification. Human review remains required.
---
 docs/python-api.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/python-api.rst b/docs/python-api.rst
index d515642a5..2849f7fb1 100644
--- a/docs/python-api.rst
+++ b/docs/python-api.rst
@@ -185,7 +185,7 @@ You can attach an additional database using the ``.attach()`` method, providing
 You can reference tables in the attached database using the alias value you passed to ``db.attach(alias, filepath)`` as a prefix, for example the ``second.table_in_second`` reference in the SQL query above.
 
 .. note::
-    In the CLI: :ref:`sqlite-utils --attach <cli_query_attach>`
+    In the CLI: :ref:`sqlite-utils <cli_query_attach>` ``--attach``
 
 .. _python_api_tracing:
 
@@ -1025,7 +1025,7 @@ Here's an example that uses these features:
 
 
 .. note::
-    In the CLI: :ref:`sqlite-utils insert --not-null and --default <cli_defaults_not_null>`
+    In the CLI: :ref:`sqlite-utils insert <cli_defaults_not_null>` ``--not-null`` and ``--default``
 
 .. _python_api_rename_table:
 
@@ -1188,7 +1188,7 @@ To replace any existing records that have a matching primary key, use the ``repl
     Prior to sqlite-utils 2.0 the ``.upsert()`` and ``.upsert_all()`` methods worked the same way as ``.insert(replace=True)`` does today. See :ref:`python_api_upsert` for the new behaviour of those methods introduced in 2.0.
 
 .. note::
-    In the CLI: :ref:`sqlite-utils insert --replace <cli_insert_replace>`
+    In the CLI: :ref:`sqlite-utils insert <cli_insert_replace>` ``--replace``
 
 .. _python_api_update:
 
@@ -1657,7 +1657,7 @@ You can insert or update data that includes new columns and have the table autom
     new_table.insert({"name": "Gareth", "age": 32, "shoe_size": 11})
 
 .. note::
-    In the CLI: :ref:`sqlite-utils insert --alter <cli_add_column_alter>`
+    In the CLI: :ref:`sqlite-utils insert <cli_add_column_alter>` ``--alter``
 
 .. _python_api_add_foreign_key:
 
@@ -3360,7 +3360,7 @@ You can cause ``sqlite3`` to return more useful errors, including the traceback
     sqlite3.enable_callback_tracebacks(True)
 
 .. note::
-    In the CLI: :ref:`sqlite-utils query --functions <cli_query_functions>`
+    In the CLI: :ref:`sqlite-utils query <cli_query_functions>` ``--functions``
 
 .. _python_api_quote:
 
@@ -3495,7 +3495,7 @@ Initialize SpatiaLite
    :noindex:
 
 .. note::
-    In the CLI: :ref:`sqlite-utils create-database --init-spatialite <cli_create_database>`
+    In the CLI: :ref:`sqlite-utils create-database <cli_create_database>` ``--init-spatialite``
 
 .. _python_api_gis_find_spatialite: