datasette create-token command, refs #1859

docs/authentication.rst

@@ -352,6 +352,29 @@ This page cannot be accessed by actors with a ``"token": "some-value"`` property
 
 You can disable this feature using the :ref:`allow_signed_tokens <setting_allow_signed_tokens>` setting.
 
+.. _authentication_cli_create_token:
+
+datasette create-token
+----------------------
+
+You can also create tokens on the command line using the ``datasette create-token`` command.
+
+This command takes one required argument - the ID of the actor to be associated with the created token.
+
+You can specify an ``--expires-after`` option in seconds. If omitted, the token will never expire.
+
+The command will sign the token using the ``DATASETTE_SECRET`` environment variable, if available. You can also pass the secret using the ``--secret`` option.
+
+This means you can run the command locally to create tokens for use with a deployed Datasette instance, provided you know that instance's secret.
+
+To create a token for the ``root`` actor that will expire in one hour::
+
+    datasette create-token root --expires-after 3600
+
+To create a secret that never expires using a specific secret::
+
+    datasette create-token root --secret my-secret-goes-here
+
 .. _permissions_plugins:
 
 Checking permissions in plugins

docs/cli-reference.rst

@@ -47,13 +47,14 @@ Running ``datasette --help`` shows a list of all of the available commands.
       --help     Show this message and exit.
 
     Commands:
-      serve*     Serve up specified SQLite database files with a web UI
-      inspect    Generate JSON summary of provided database files
-      install    Install plugins and packages from PyPI into the same...
-      package    Package SQLite files into a Datasette Docker container
-      plugins    List currently installed plugins
-      publish    Publish specified SQLite database files to the internet along...
-      uninstall  Uninstall plugins and Python packages from the Datasette...
+      serve*        Serve up specified SQLite database files with a web UI
+      create-token  Create a signed API token for the specified actor ID
+      inspect       Generate JSON summary of provided database files
+      install       Install plugins and packages from PyPI into the same...
+      package       Package SQLite files into a Datasette Docker container
+      plugins       List currently installed plugins
+      publish       Publish specified SQLite database files to the internet...
+      uninstall     Uninstall plugins and Python packages from the Datasette...
 
 
 .. [[[end]]]
@@ -591,3 +592,31 @@ This performance optimization is used automatically by some of the ``datasette p
 
 
 .. [[[end]]]
+
+
+.. _cli_help_create_token___help:
+
+datasette create-token
+======================
+
+Create a signed API token, see :ref:`authentication_cli_create_token`.
+
+.. [[[cog
+    help(["create-token", "--help"])
+.. ]]]
+
+::
+
+    Usage: datasette create-token [OPTIONS] ID
+
+      Create a signed API token for the specified actor ID
+
+    Options:
+      --secret TEXT                Secret used for signing the API tokens
+                                   [required]
+      -e, --expires-after INTEGER  Token should expire after this many seconds
+      --debug                      Show decoded token
+      --help                       Show this message and exit.
+
+
+.. [[[end]]]

docs/plugins.rst

@@ -152,7 +152,8 @@ If you run ``datasette plugins --all`` it will include default plugins that ship
             "version": null,
             "hooks": [
                 "actor_from_request",
-                "permission_allowed"
+                "permission_allowed",
+                "register_commands"
             ]
         },
         {