mirror of https://github.com/simonw/dclient.git synced 2026-07-23 17:34:32 +02:00

Simon Willison 92c0d2a5ba Tests and docs for v2 introspection commands and alias features

Add test_commands_v2.py with 28 tests covering databases, tables,
plugins, schema, default_query, upsert, auth status, actor, and
get commands.

Add test_alias_v2.py with 5 tests for alias default, alias default-db,
and removing the default alias.

Update aliases.md and authentication.md docs for v2 API.

refs #29

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-24 15:21:58 -08:00

4.6 KiB

Raw Permalink Blame History

(authentication)=

Authentication

dclient can handle API tokens for Datasette instances that require authentication.

You can pass an API token to any command using --token like this:

dclient query fixtures "select * from facetable" --token dstok_mytoken -i latest

A more convenient way to handle this is to store tokens for your aliases.

Using stored tokens

To store a token for an alias:

dclient auth add latest

Then paste in the token and hit enter when prompted to do so.

Tokens can also be stored for direct URLs:

dclient auth add https://latest.datasette.io

To list which aliases/URLs you have set tokens for, run the auth list command:

dclient auth list

To delete the token for a specific alias or URL, run auth remove:

dclient auth remove latest

Token resolution order

When making a request, dclient resolves the token in this order:

--token CLI flag (highest priority)
Token stored by alias name in auth.json
Token stored by URL prefix in auth.json
DATASETTE_TOKEN environment variable (lowest priority)

Testing a token

The dclient auth status command can be used to verify authentication by calling /-/actor.json:

dclient auth status
dclient auth status -i prod

The dclient actor command also shows the actor:

dclient actor
dclient actor -i prod

The output looks like this:

{
    "actor": {
        "id": "root",
        "token": "dstok"
    }
}

dclient auth --help

Usage: dclient auth [OPTIONS] COMMAND [ARGS]...

  Manage authentication for different instances

Options:
  --help  Show this message and exit.

Commands:
  add     Add an authentication token for an alias or URL
  list    List stored API tokens
  remove  Remove the API token for an alias or URL
  status  Verify authentication by calling /-/actor.json

dclient auth add --help

Usage: dclient auth add [OPTIONS] ALIAS_OR_URL

  Add an authentication token for an alias or URL

  Example usage:

      dclient auth add prod
      dclient auth add https://datasette.io

  Paste in the token when prompted.

Options:
  --token TEXT
  --help        Show this message and exit.

dclient auth list --help

Usage: dclient auth list [OPTIONS]

  List stored API tokens

  Example usage:

      dclient auth list

Options:
  --help  Show this message and exit.

dclient auth remove --help

Usage: dclient auth remove [OPTIONS] ALIAS_OR_URL

  Remove the API token for an alias or URL

  Example usage:

      dclient auth remove prod

Options:
  --help  Show this message and exit.

dclient auth status --help

Usage: dclient auth status [OPTIONS]

  Verify authentication by calling /-/actor.json

  Example usage:

      dclient auth status
      dclient auth status -i prod

Options:
  -i, --instance TEXT  Datasette instance URL or alias
  --token TEXT         API token
  --help               Show this message and exit.

dclient actor --help

Usage: dclient actor [OPTIONS]

  Show the actor represented by an API token

  Example usage:

      dclient actor
      dclient actor -i prod

Options:
  -i, --instance TEXT  Datasette instance URL or alias
  --token TEXT         API token
  --help               Show this message and exit.

4.6 KiB Raw Permalink Blame History