From 081aeb32a284937669e293b34f61614b1af79c8e Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sun, 25 Feb 2024 11:24:46 -0800
Subject: [PATCH] Example usage in --help, closes #22

---
 dclient/cli.py         | 56 ++++++++++++++++++++++++++++++++++++++----
 docs/aliases.md        | 16 ++++++++++++
 docs/authentication.md |  8 ++++++
 docs/queries.md        |  6 +++++
 4 files changed, 81 insertions(+), 5 deletions(-)

diff --git a/dclient/cli.py b/dclient/cli.py
index 009fb9e..04f4681 100644
--- a/dclient/cli.py
+++ b/dclient/cli.py
@@ -27,6 +27,13 @@ def query(url_or_alias, sql, token):
     Run a SQL query against a Datasette database URL
 
     Returns a JSON array of objects
+
+    Example usage:
+
+    \b
+        dclient query \\
+          https://datasette.io/content \\
+          'select * from news limit 10'
     """
     aliases_file = get_config_dir() / "aliases.json"
     aliases = _load_aliases(aliases_file)
@@ -247,7 +254,14 @@ def alias():
 @alias.command(name="list")
 @click.option("_json", "--json", is_flag=True, help="Output raw JSON")
 def list_(_json):
-    "List aliases"
+    """
+    List aliases
+
+    Example usage:
+
+    \b
+        dclient aliases list
+    """
     aliases_file = get_config_dir() / "aliases.json"
     aliases = _load_aliases(aliases_file)
     if _json:
@@ -261,7 +275,18 @@ def list_(_json):
 @click.argument("name")
 @click.argument("url")
 def alias_add(name, url):
-    "Add an alias"
+    """
+    Add an alias
+
+    Example usage:
+
+    \b
+        dclient alias add content https://datasette.io/content
+
+    Then:
+
+        dclient query content 'select * from news limit 3'
+    """
     config_dir = get_config_dir()
     config_dir.mkdir(parents=True, exist_ok=True)
     aliases_file = config_dir / "aliases.json"
@@ -273,7 +298,14 @@ def alias_add(name, url):
 @alias.command(name="remove")
 @click.argument("name")
 def alias_remove(name):
-    "Remove an alias"
+    """
+    Remove an alias
+
+    Example usage:
+
+    \b
+        dclient alias remove content
+    """
     config_dir = get_config_dir()
     aliases_file = config_dir / "aliases.json"
     aliases = _load_aliases(aliases_file)
@@ -318,7 +350,14 @@ def auth_add(alias_or_url, token):
 
 @auth.command(name="list")
 def auth_list():
-    "List stored API tokens"
+    """
+    List stored API tokens
+
+    Example usage:
+
+    \b
+        dclient auth list
+    """
     auths_file = get_config_dir() / "auth.json"
     click.echo("Tokens file: {}".format(auths_file))
     auths = _load_auths(auths_file)
@@ -331,7 +370,14 @@ def auth_list():
 @auth.command(name="remove")
 @click.argument("alias_or_url")
 def auth_remove(alias_or_url):
-    "Remove the API token for an alias or URL"
+    """
+    Remove the API token for an alias or URL
+
+    Example usage:
+
+    \b
+        dclient auth remove https://datasette.io/content
+    """
     config_dir = get_config_dir()
     auth_file = config_dir / "auth.json"
     auths = _load_auths(auth_file)
diff --git a/docs/aliases.md b/docs/aliases.md
index 6c0697f..3bb6f7c 100644
--- a/docs/aliases.md
+++ b/docs/aliases.md
@@ -56,6 +56,10 @@ Usage: dclient alias list [OPTIONS]
 
   List aliases
 
+  Example usage:
+
+      dclient aliases list
+
 Options:
   --json  Output raw JSON
   --help  Show this message and exit.
@@ -78,6 +82,14 @@ Usage: dclient alias add [OPTIONS] NAME URL
 
   Add an alias
 
+  Example usage:
+
+      dclient alias add content https://datasette.io/content
+
+  Then:
+
+      dclient query content 'select * from news limit 3'
+
 Options:
   --help  Show this message and exit.
 
@@ -99,6 +111,10 @@ Usage: dclient alias remove [OPTIONS] NAME
 
   Remove an alias
 
+  Example usage:
+
+      dclient alias remove content
+
 Options:
   --help  Show this message and exit.
 
diff --git a/docs/authentication.md b/docs/authentication.md
index 40e2dd7..e360fa0 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -101,6 +101,10 @@ Usage: dclient auth list [OPTIONS]
 
   List stored API tokens
 
+  Example usage:
+
+      dclient auth list
+
 Options:
   --help  Show this message and exit.
 
@@ -122,6 +126,10 @@ Usage: dclient auth remove [OPTIONS] ALIAS_OR_URL
 
   Remove the API token for an alias or URL
 
+  Example usage:
+
+      dclient auth remove https://datasette.io/content
+
 Options:
   --help  Show this message and exit.
 
diff --git a/docs/queries.md b/docs/queries.md
index 6ce1504..7dfd295 100644
--- a/docs/queries.md
+++ b/docs/queries.md
@@ -43,6 +43,12 @@ Usage: dclient query [OPTIONS] URL_OR_ALIAS SQL
 
   Returns a JSON array of objects
 
+  Example usage:
+
+      dclient query \
+        https://datasette.io/content \
+        'select * from news limit 10'
+
 Options:
   --token TEXT  API token
   --help        Show this message and exit.