mirror of
https://github.com/simonw/dclient.git
synced 2026-07-30 22:14:23 +02:00
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>
This commit is contained in:
Simon Willison
parent
3621f13263
commit
92c0d2a5ba
4 changed files with 812 additions and 36 deletions
111
docs/aliases.md
111
docs/aliases.md
|
|
@ -1,17 +1,40 @@
|
|||
# Aliases
|
||||
|
||||
You can assign an alias to a Datasette database using the `dclient alias` command:
|
||||
You can assign an alias to a Datasette instance using the `dclient alias add` command:
|
||||
|
||||
dclient alias add content https://datasette.io/content
|
||||
dclient alias add latest https://latest.datasette.io
|
||||
|
||||
You can list aliases with `dclient alias list`:
|
||||
|
||||
$ dclient alias list
|
||||
content = https://datasette.io/content
|
||||
latest = https://latest.datasette.io
|
||||
|
||||
Once registered, you can pass an alias to commands such as `dclient query`:
|
||||
Once registered, you can pass an alias to commands using the `-i` flag:
|
||||
|
||||
dclient query content "select * from news limit 1"
|
||||
dclient query fixtures "select * from news limit 1" -i latest
|
||||
|
||||
## Default instance
|
||||
|
||||
Set a default instance so you don't need `-i` every time:
|
||||
|
||||
dclient alias default latest
|
||||
|
||||
Now commands will use `latest` automatically:
|
||||
|
||||
dclient databases
|
||||
dclient tables -d fixtures
|
||||
|
||||
## Default database
|
||||
|
||||
Set a default database for an alias:
|
||||
|
||||
dclient alias default-db latest fixtures
|
||||
|
||||
Now you can run bare SQL queries directly:
|
||||
|
||||
dclient "select * from facetable limit 5"
|
||||
|
||||
This uses the default instance and default database.
|
||||
|
||||
## dclient alias --help
|
||||
<!-- [[[cog
|
||||
|
|
@ -34,9 +57,11 @@ Options:
|
|||
--help Show this message and exit.
|
||||
|
||||
Commands:
|
||||
add Add an alias
|
||||
list List aliases
|
||||
remove Remove an alias
|
||||
add Add an alias for a Datasette instance
|
||||
default Set or show the default instance
|
||||
default-db Set or show the default database for an alias
|
||||
list List aliases
|
||||
remove Remove an alias
|
||||
|
||||
```
|
||||
<!-- [[[end]]] -->
|
||||
|
|
@ -56,10 +81,6 @@ Usage: dclient alias list [OPTIONS]
|
|||
|
||||
List aliases
|
||||
|
||||
Example usage:
|
||||
|
||||
dclient aliases list
|
||||
|
||||
Options:
|
||||
--json Output raw JSON
|
||||
--help Show this message and exit.
|
||||
|
|
@ -80,15 +101,11 @@ cog.out(
|
|||
```
|
||||
Usage: dclient alias add [OPTIONS] NAME URL
|
||||
|
||||
Add an alias
|
||||
Add an alias for a Datasette instance
|
||||
|
||||
Example usage:
|
||||
|
||||
dclient alias add content https://datasette.io/content
|
||||
|
||||
Then:
|
||||
|
||||
dclient query content 'select * from news limit 3'
|
||||
dclient alias add prod https://myapp.datasette.cloud
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
|
|
@ -113,10 +130,66 @@ Usage: dclient alias remove [OPTIONS] NAME
|
|||
|
||||
Example usage:
|
||||
|
||||
dclient alias remove content
|
||||
dclient alias remove prod
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
|
||||
```
|
||||
<!-- [[[end]]] -->
|
||||
|
||||
## dclient alias default --help
|
||||
|
||||
<!-- [[[cog
|
||||
import cog
|
||||
result = runner.invoke(cli.cli, ["alias", "default", "--help"])
|
||||
help = result.output.replace("Usage: cli", "Usage: dclient")
|
||||
cog.out(
|
||||
"```\n{}\n```".format(help)
|
||||
)
|
||||
]]] -->
|
||||
```
|
||||
Usage: dclient alias default [OPTIONS] [NAME]
|
||||
|
||||
Set or show the default instance
|
||||
|
||||
Example usage:
|
||||
|
||||
dclient alias default prod
|
||||
dclient alias default
|
||||
dclient alias default --clear
|
||||
|
||||
Options:
|
||||
--clear Clear default instance
|
||||
--help Show this message and exit.
|
||||
|
||||
```
|
||||
<!-- [[[end]]] -->
|
||||
|
||||
## dclient alias default-db --help
|
||||
|
||||
<!-- [[[cog
|
||||
import cog
|
||||
result = runner.invoke(cli.cli, ["alias", "default-db", "--help"])
|
||||
help = result.output.replace("Usage: cli", "Usage: dclient")
|
||||
cog.out(
|
||||
"```\n{}\n```".format(help)
|
||||
)
|
||||
]]] -->
|
||||
```
|
||||
Usage: dclient alias default-db [OPTIONS] ALIAS_NAME [DB]
|
||||
|
||||
Set or show the default database for an alias
|
||||
|
||||
Example usage:
|
||||
|
||||
dclient alias default-db prod main
|
||||
dclient alias default-db prod
|
||||
dclient alias default-db prod --clear
|
||||
|
||||
Options:
|
||||
--clear Clear default database for this alias
|
||||
--help Show this message and exit.
|
||||
|
||||
```
|
||||
<!-- [[[end]]] -->
|
||||
|
|
|
|||
|
|
@ -4,35 +4,57 @@
|
|||
|
||||
`dclient` can handle API tokens for Datasette instances that require authentication.
|
||||
|
||||
You can pass an API token to `query` using `-t/--token` like this:
|
||||
You can pass an API token to any command using `--token` like this:
|
||||
|
||||
```bash
|
||||
dclient query https://latest.datasette.io/fixtures "select * from facetable" -t dstok_mytoken
|
||||
dclient query fixtures "select * from facetable" --token dstok_mytoken -i latest
|
||||
```
|
||||
|
||||
A more convenient way to handle this is to store tokens to be used with different URL prefixes.
|
||||
A more convenient way to handle this is to store tokens for your aliases.
|
||||
|
||||
## Using stored tokens
|
||||
|
||||
To always use `dstok_mytoken` for any URL on the `https://latest.datasette.io/` instance you can run this:
|
||||
To store a token for an alias:
|
||||
```bash
|
||||
dclient auth add https://latest.datasette.io/
|
||||
dclient auth add latest
|
||||
```
|
||||
Then paste in the token and hit enter when prompted to do so.
|
||||
|
||||
To list which URLs you have set tokens for, run the `auth list` command:
|
||||
Tokens can also be stored for direct URLs:
|
||||
```bash
|
||||
dclient auth add https://latest.datasette.io
|
||||
```
|
||||
|
||||
To list which aliases/URLs you have set tokens for, run the `auth list` command:
|
||||
```bash
|
||||
dclient auth list
|
||||
```
|
||||
To delete the token for a specific URL, run `auth remove`:
|
||||
To delete the token for a specific alias or URL, run `auth remove`:
|
||||
```bash
|
||||
dclient auth remove https://latest.datasette.io/
|
||||
dclient auth remove latest
|
||||
```
|
||||
|
||||
## Token resolution order
|
||||
|
||||
When making a request, dclient resolves the token in this order:
|
||||
|
||||
1. `--token` CLI flag (highest priority)
|
||||
2. Token stored by alias name in `auth.json`
|
||||
3. Token stored by URL prefix in `auth.json`
|
||||
4. `DATASETTE_TOKEN` environment variable (lowest priority)
|
||||
|
||||
## Testing a token
|
||||
|
||||
The `dclient actor` command can be used to test a token, retrieving the actor that the token represents.
|
||||
The `dclient auth status` command can be used to verify authentication by calling `/-/actor.json`:
|
||||
```bash
|
||||
dclient actor https://latest.datasette.io/content
|
||||
dclient auth status
|
||||
dclient auth status -i prod
|
||||
```
|
||||
|
||||
The `dclient actor` command also shows the actor:
|
||||
```bash
|
||||
dclient actor
|
||||
dclient actor -i prod
|
||||
```
|
||||
The output looks like this:
|
||||
```json
|
||||
|
|
@ -68,6 +90,7 @@ 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
|
||||
|
||||
```
|
||||
<!-- [[[end]]] -->
|
||||
|
|
@ -89,7 +112,8 @@ Usage: dclient auth add [OPTIONS] ALIAS_OR_URL
|
|||
|
||||
Example usage:
|
||||
|
||||
dclient auth add https://datasette.io/content
|
||||
dclient auth add prod
|
||||
dclient auth add https://datasette.io
|
||||
|
||||
Paste in the token when prompted.
|
||||
|
||||
|
|
@ -142,7 +166,7 @@ Usage: dclient auth remove [OPTIONS] ALIAS_OR_URL
|
|||
|
||||
Example usage:
|
||||
|
||||
dclient auth remove https://datasette.io/content
|
||||
dclient auth remove prod
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
|
|
@ -150,6 +174,34 @@ Options:
|
|||
```
|
||||
<!-- [[[end]]] -->
|
||||
|
||||
## dclient auth status --help
|
||||
|
||||
<!-- [[[cog
|
||||
import cog
|
||||
result = runner.invoke(cli.cli, ["auth", "status", "--help"])
|
||||
help = result.output.replace("Usage: cli", "Usage: dclient")
|
||||
cog.out(
|
||||
"```\n{}\n```".format(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.
|
||||
|
||||
```
|
||||
<!-- [[[end]]] -->
|
||||
|
||||
## dclient actor --help
|
||||
|
||||
<!-- [[[cog
|
||||
|
|
@ -161,17 +213,19 @@ cog.out(
|
|||
)
|
||||
]]] -->
|
||||
```
|
||||
Usage: dclient actor [OPTIONS] [URL_OR_ALIAS]
|
||||
Usage: dclient actor [OPTIONS]
|
||||
|
||||
Show the actor represented by an API token
|
||||
|
||||
Example usage:
|
||||
|
||||
dclient actor https://latest.datasette.io/fixtures
|
||||
dclient actor
|
||||
dclient actor -i prod
|
||||
|
||||
Options:
|
||||
--token TEXT API token
|
||||
--help Show this message and exit.
|
||||
-i, --instance TEXT Datasette instance URL or alias
|
||||
--token TEXT API token
|
||||
--help Show this message and exit.
|
||||
|
||||
```
|
||||
<!-- [[[end]]] -->
|
||||
<!-- [[[end]]] -->
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue