remote/dclient
1
0
Fork 0
mirror of https://github.com/simonw/dclient.git synced 2026-09-27 12:24:13 +02:00
Code Issues Projects Releases Packages Wiki Activity

v2 config system, CLI rewrite, and updated core commands

Browse source 
Replace aliases.json with config.json storing instances with
default_database. Instance resolution: -i flag → config default →
DATASETTE_URL. Database resolution: -d flag → instance default_database →
DATASETTE_DATABASE. Token resolution: --token → auth.json by alias →
auth.json by URL → DATASETTE_TOKEN.

Add click-default-group dependency for bare SQL shortcut support.
Add DCLIENT_CONFIG_DIR env var to override config directory.

Rewrite query, insert, get, and actor commands for v2 API where
instance is always -i flag. Add upsert command sharing insert
implementation. Add databases, tables, schema, plugins commands.
Add default_query hidden command for bare SQL shortcut.

Add alias default, alias default-db subcommands.
Add auth status subcommand.

refs #29

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Simon Willison 2026-02-24 15:21:52 -08:00
commit 3621f13263
10 changed files with 1049 additions and 314 deletions
Download patch file Download diff file Expand all files Collapse all files

45
docs/environment.md
View file

@ -2,37 +2,39 @@
# Environment variables
`dclient` supports two environment variables for convenient access to a Datasette instance without needing aliases or repeated URLs.
`dclient` supports several environment variables for convenient access to Datasette instances.
## DATASETTE_URL
Set this to the base URL of your Datasette instance:
Set this to the base URL of your Datasette instance. It is used as a fallback when no instance is specified via `-i` and no default instance is configured:
```bash
export DATASETTE_URL=https://my-instance.datasette.cloud
```
Then pass just the database name as the first argument to any command:
Then you can omit the `-i` flag:
```bash
dclient databases
dclient query data "select * from my_table limit 10"
```
This is equivalent to:
Aliases and the `-i` flag always take priority over `DATASETTE_URL`.
## DATASETTE_DATABASE
Set this to a default database name. It is used as a fallback when no database is specified via `-d` and the current instance has no `default_database` configured:
```bash
dclient query https://my-instance.datasette.cloud/data "select * from my_table limit 10"
export DATASETTE_DATABASE=data
```
It works with all commands:
Then you can use the bare SQL shortcut:
```bash
dclient insert data my_table data.csv --csv
dclient actor data
dclient "select * from my_table limit 10"
```
Full URLs and aliases always take priority over `DATASETTE_URL`. If the argument starts with `http://` or `https://`, it is used as-is. If it matches an alias in `aliases.json`, the alias is used.
## DATASETTE_TOKEN
Set this to an API token:
@ -46,23 +48,34 @@ The token will be used automatically for any request that doesn't have a more sp
The precedence order for tokens is:
1. `--token` CLI flag (highest priority)
2. Stored token from `auth.json` (matched by URL prefix)
2. Stored token from `auth.json` (matched by alias name, then URL prefix)
3. `DATASETTE_TOKEN` environment variable (lowest priority)
## Using both together
## DCLIENT_CONFIG_DIR
Override the config directory (default `~/.config/io.datasette.dclient` or platform equivalent):
```bash
export DCLIENT_CONFIG_DIR=/path/to/config
```
This is useful for testing or running multiple configurations side by side.
## Using them together
These variables work well together for quick access to a single instance:
```bash
export DATASETTE_URL=https://my-instance.datasette.cloud
export DATASETTE_DATABASE=data
export DATASETTE_TOKEN=dstok_abc123
# Query the "data" database
dclient query data "select * from my_table"
# Query
dclient "select * from my_table"
# Insert into the "data" database
# Insert
cat records.json | dclient insert data my_table - --json
# Check your actor identity
dclient actor data
dclient actor
```

69
docs/inserting.md
View file

@ -4,19 +4,23 @@ The `dclient insert` command can be used to insert data from a local file direct
First you'll need to {ref}`authenticate <authentication>` with the instance.
To insert data from a `data.csv` file into a table called `my_table`, creating that table if it does not exist:
To insert data from a `data.csv` file into a table called `my_table` in the `data` database:
```bash
dclient insert \
https://my-private-space.datasette.cloud/data \
my_table data.csv --create
dclient insert data my_table data.csv --create -i myapp
```
You can also pipe data into standard input:
```bash
curl -s 'https://api.github.com/repos/simonw/dclient/issues' | \
dclient insert \
https://my-private-space.datasette.cloud/data \
issues - --create
dclient insert data issues - --create -i myapp
```
## Upserting data
The `dclient upsert` command works exactly like `insert` but uses the upsert endpoint, which will update existing rows with matching primary keys rather than raising an error.
```bash
dclient upsert data my_table data.csv --csv -i myapp
```
## Streaming data
@ -26,7 +30,7 @@ curl -s 'https://api.github.com/repos/simonw/dclient/issues' | \
If you have a log file containing newline-delimited JSON you can tail it and send it to a Datasette instance like this:
```bash
tail -f log.jsonl | \
dclient insert https://my-private-space.datasette.cloud/data logs - --nl
dclient insert data logs - --nl -i myapp
```
When reading from standard input (filename `-`) you are required to specify the format. In this example that's `--nl` for newline-delimited JSON. `--csv` and `--tsv` are supported for streaming as well, but `--json` is not.
@ -34,7 +38,7 @@ In streaming mode records default to being sent to the server every 100 records
```bash
tail -f log.jsonl | dclient insert \
https://my-private-space.datasette.cloud/data logs - --nl --create \
data logs - --nl --create -i myapp \
--batch-size 10 \
--interval 5
```
@ -106,26 +110,65 @@ cog.out(
)
]]] -->
```
Usage: dclient insert [OPTIONS] URL_OR_ALIAS TABLE FILEPATH
Usage: dclient insert [OPTIONS] DATABASE TABLE FILEPATH
Insert data into a remote Datasette instance
Example usage:
dclient insert \
https://private.datasette.cloud/data \
mytable data.csv --pk id --create
dclient insert main mytable data.csv --csv -i myapp
dclient insert main mytable data.csv --csv --create --pk id
Options:
-i, --instance TEXT Datasette instance URL or alias
--csv Input is CSV
--tsv Input is TSV
--json Input is JSON
--nl Input is newline-delimited JSON
--encoding TEXT Character encoding for CSV/TSV
--no-detect-types Don't detect column types for CSV/TSV
--alter Alter table to add any missing columns
--pk TEXT Columns to use as the primary key when creating the
table
--batch-size INTEGER Send rows in batches of this size
--interval FLOAT Send batch at least every X seconds
-t, --token TEXT API token
--silent Don't output progress
-v, --verbose Verbose output: show HTTP request and response
--replace Replace rows with a matching primary key
--ignore Ignore rows with a matching primary key
--create Create table if it does not exist
--help Show this message and exit.
```
<!-- [[[end]]] -->
## dclient upsert --help
<!-- [[[cog
import cog
result = runner.invoke(cli.cli, ["upsert", "--help"])
help = result.output.replace("Usage: cli", "Usage: dclient")
cog.out(
"```\n{}\n```".format(help)
)
]]] -->
```
Usage: dclient upsert [OPTIONS] DATABASE TABLE FILEPATH
Upsert data into a remote Datasette instance
Example usage:
dclient upsert main mytable data.csv --csv -i myapp
Options:
-i, --instance TEXT Datasette instance URL or alias
--csv Input is CSV
--tsv Input is TSV
--json Input is JSON
--nl Input is newline-delimited JSON
--encoding TEXT Character encoding for CSV/TSV
--no-detect-types Don't detect column types for CSV/TSV
--alter Alter table to add any missing columns
--pk TEXT Columns to use as the primary key when creating the
table

32
docs/queries.md
View file

@ -3,7 +3,7 @@
You can run SQL queries against a Datasette instance like this:
```bash
dclient query https://latest.datasette.io/fixtures "select * from facetable limit 1"
dclient query fixtures "select * from facetable limit 1" -i https://latest.datasette.io
```
Output:
```json
@ -24,6 +24,18 @@ Output:
]
```
The `query` command takes a database name and SQL string as positional arguments. Use `-i` to specify the instance (alias or URL). If you have a default instance and default database configured, you can use the bare SQL shortcut instead:
```bash
dclient "select * from facetable limit 1"
```
You can override just the database with `-d`:
```bash
dclient "select * from counters" -d counters
```
## dclient query --help
<!-- [[[cog
import cog
@ -37,22 +49,22 @@ cog.out(
)
]]] -->
```
Usage: dclient query [OPTIONS] URL_OR_ALIAS SQL
Usage: dclient query [OPTIONS] DATABASE SQL
Run a SQL query against a Datasette database URL
Run a SQL query against a Datasette database
Returns a JSON array of objects
Requires both a database name and a SQL string.
Example usage:
dclient query \
https://datasette.io/content \
'select * from news limit 10'
dclient query fixtures "select * from facetable limit 5"
dclient query analytics "select count(*) from events" -i staging
Options:
--token TEXT API token
-v, --verbose Verbose output: show HTTP request
--help Show this message and exit.
-i, --instance TEXT Datasette instance URL or alias
--token TEXT API token
-v, --verbose Verbose output: show HTTP request
--help Show this message and exit.
```
<!-- [[[end]]] -->