runtime website docs
This commit is contained in:
@@ -3,9 +3,10 @@ An attempt at documenting the changes/new features introduced in each release.
|
||||
## Edge
|
||||
Whenever a commit is pushed to the `main` branch, within ~5 minutes, it will be released as a docker image with the `:v2` tag, and a binary in the [edge release](https://github.com/silverbulletmd/silverbullet/releases/tag/edge). If you want to live on the bleeding edge of SilverBullet goodness (or regression) this is where to do it.
|
||||
|
||||
* New `SB_DISABLE_SERVICE_WORKER` : server-side switch to disable the client service worker for all clients, this will disable sync (all loads and saves will go directly to the server) and disable any offline support.
|
||||
* New built-in [[Journal]] library.
|
||||
* [[X-Ray]]: an editor lens (run `Editor: Toggle X-Ray`) to inspect indexed objects inline.
|
||||
* New built-in [[Journal]] library.
|
||||
* Runtime API: Expose objects (with filter) `/.runtime/objects/*` for external integrations and the [[CLI]], see [[Runtime API]].
|
||||
* New `SB_DISABLE_SERVICE_WORKER` : server-side switch to disable the client service worker for all clients, this will disable sync (all loads and saves will go directly to the server) and disable any offline support.
|
||||
* UX: now showing spinners instead of underlying (Lua) code in states where widgets aren't ready to render yet (e.g. before an initial index hasn't completed)
|
||||
* Fix: indexed `range` for `data` blocks (and `#tag` data blocks) now points at the YAML content instead of the surrounding fence markers; multi-document blocks now compute per-doc ranges correctly.
|
||||
* `sb` CLI changed how it encrypts secrets, so if you used token or password-based auth you need to re-add your space.
|
||||
|
||||
@@ -77,6 +77,49 @@ Special commands inside the REPL:
|
||||
|
||||
The REPL automatically detects incomplete expressions (unclosed brackets, blocks) and waits for more input.
|
||||
|
||||
## `get [tag] [ref]`
|
||||
List indexed tags, list objects of a tag, or fetch a single object — kubectl-style ergonomics on top of the [[Runtime API]]'s `/.runtime/objects/*` endpoints.
|
||||
|
||||
```bash
|
||||
sb get # list all known tag names
|
||||
sb get task # list all task objects
|
||||
sb get meta/library # list all libraries
|
||||
sb get page "Daily/2026-05-14" # fetch a single page by ref
|
||||
```
|
||||
|
||||
Filtering, ordering, paging, and projection:
|
||||
|
||||
```bash
|
||||
# Unfinished tasks, highest priority first, top 20
|
||||
sb get task -l done=false --sort-by priority:desc --limit 20
|
||||
|
||||
# Tasks in any of several statuses
|
||||
sb get task --where status:in=open,pending,blocked
|
||||
|
||||
# Pages starting with a prefix
|
||||
sb get page --where name:startsWith=2026-
|
||||
|
||||
# Project only the fields you care about
|
||||
sb get page --where meta.author=alice --select name,lastModified
|
||||
```
|
||||
|
||||
Operators for `--where`: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `startsWith`. Use `field:OP=value` form, e.g. `--where due:lte=2026-06-01`. Multiple `--where` flags are AND-ed.
|
||||
|
||||
Values are auto-typed (`42` → number, `true`/`false` → boolean, `null` → nil, else string). Force a type with a prefix: `--where zipCode=str:01234`, `--where count:gt=num:10`, `--where active=bool:true`.
|
||||
|
||||
Output:
|
||||
|
||||
| Flag | Behavior |
|
||||
|---|---|
|
||||
| `-o auto` (default) | Table on a TTY or with `--text`; JSON otherwise |
|
||||
| `-o table` | kubectl-style aligned columns. Up to 8 columns picked from common fields; cells truncated at 40 chars |
|
||||
| `-o json` | Pretty-printed JSON array |
|
||||
| `-o jsonl` | One JSON object per line (good for `xargs` / line-oriented pipes) |
|
||||
| `-o yaml` | YAML |
|
||||
| `-v, --verbose` | Adds the synthesized Lua query as `X-Equivalent-Lua` response header |
|
||||
|
||||
Exit codes: `0` success, `1` transport error, `2` API error (non-2xx other than 404), `3` not found (404 — only meaningful for the `sb get <tag> <ref>` form).
|
||||
|
||||
## `logs`
|
||||
Show console logs from the headless browser client.
|
||||
|
||||
|
||||
+83
-6
@@ -1,6 +1,6 @@
|
||||
#maturity/experimental
|
||||
|
||||
The Runtime API lets you interact with SilverBullet programmatically over HTTP — evaluate Lua expressions and run scripts from the command line, scripts, or external tools.
|
||||
The Runtime API lets you interact with SilverBullet programmatically over HTTP: evaluate Lua expressions and run scripts from the command line, scripts, or external tools.
|
||||
|
||||
Requests are evaluated via Chrome DevTools Protocol (CDP) in a headless Chrome instance, which does the actual execution so all results reflect the live client state.
|
||||
|
||||
@@ -77,6 +77,72 @@ Captures the current viewport of the headless Chrome instance as a PNG image.
|
||||
curl -o screenshot.png http://localhost:3000/.runtime/screenshot
|
||||
```
|
||||
|
||||
## List object tags
|
||||
`GET /.runtime/objects`
|
||||
|
||||
Returns every tag indexed in the current space as a bare JSON array of strings.
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $SB_TOKEN" \
|
||||
http://localhost:3000/.runtime/objects
|
||||
# => ["header", "item", "page", "task"]
|
||||
```
|
||||
|
||||
## List objects by tag
|
||||
`GET /.runtime/objects/{tag}`
|
||||
|
||||
Returns a JSON array of objects carrying the given tag. Supports filtering, ordering, pagination, and projection via query parameters.
|
||||
|
||||
| Query parameter | Meaning |
|
||||
|---|---|
|
||||
| `where[field]=value` | Equality filter. Repeat across fields for AND. |
|
||||
| `where[field][op]=value` | Operator filter. Supported `op`s: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `startsWith`. |
|
||||
| `order=field` or `order=field:desc` | Sort key. Repeatable for multi-key sort. |
|
||||
| `limit=N` | Default 100, max 1000. |
|
||||
| `offset=N` | Default 0. |
|
||||
| `select=f1,f2` | Projection — return only these fields per object. |
|
||||
| `debug=1` | Adds an `X-Equivalent-Lua` response header showing the Lua query that ran. |
|
||||
|
||||
Dotted field paths are supported for nested objects: `where[meta.author]=alice`.
|
||||
|
||||
Tag (and ref) values may contain `/` — for example SilverBullet's built-in `meta/library` and `meta/template/page` tags. Encode the `/` as `%2F` in the URL path; the server unescapes one segment for `{tag}` and one for `{ref}`. So `meta/library` becomes `meta%2Flibrary`, and the page named `Daily/2026-05-14` becomes `Daily%2F2026-05-14`. The `sb` CLI does this automatically.
|
||||
|
||||
The response is a bare JSON array. Paginate by stepping `offset` in increments of `limit` until you get fewer than `limit` items back.
|
||||
|
||||
```bash
|
||||
# Unfinished tasks, highest priority first, top 20
|
||||
curl -H "Authorization: Bearer $SB_TOKEN" \
|
||||
"http://localhost:3000/.runtime/objects/task?where[done]=false&order=priority:desc&limit=20"
|
||||
|
||||
# Pages by a specific author, projecting only name + lastModified
|
||||
curl -H "Authorization: Bearer $SB_TOKEN" \
|
||||
"http://localhost:3000/.runtime/objects/page?where[meta.author]=alice&select=name,lastModified"
|
||||
|
||||
# Tag containing a slash: encode the slash as %2F
|
||||
curl -H "Authorization: Bearer $SB_TOKEN" \
|
||||
"http://localhost:3000/.runtime/objects/meta%2Flibrary"
|
||||
```
|
||||
|
||||
### Value typing
|
||||
Query-string values are auto-typed:
|
||||
|
||||
* `42`, `-3.14` → number
|
||||
* `true`, `false` → boolean
|
||||
* `null` → nil (matches missing or explicit-null fields)
|
||||
* everything else → string
|
||||
|
||||
Force a type with a prefix: `where[zipCode]=str:01234`, `where[count][gt]=num:10`, `where[active]=bool:true`.
|
||||
|
||||
## Fetch a single object
|
||||
`GET /.runtime/objects/{tag}/{ref}`
|
||||
|
||||
Returns the object as JSON, or `404` if not found.
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $SB_TOKEN" \
|
||||
"http://localhost:3000/.runtime/objects/page/My%20Page"
|
||||
```
|
||||
|
||||
## Console logs
|
||||
`GET /.runtime/logs`
|
||||
|
||||
@@ -116,12 +182,23 @@ curl -H "X-Timeout: 60" \
|
||||
```
|
||||
|
||||
# Error handling
|
||||
All error responses are JSON with `Content-Type: application/json` and an `error` key:
|
||||
All error responses are JSON with `Content-Type: application/json` and an `error` key. The objects API additionally returns a `code` field with a stable machine-readable identifier:
|
||||
|
||||
* **400** — Empty request body: `{"error": "Request body is required"}`
|
||||
* **500** — Lua execution error: `{"error": "<error message>"}`
|
||||
* **503** — Runtime API not enabled or no headless browser running: `{"error": "No headless browser running"}`
|
||||
* **504** — Timeout exceeded: `{"error": "Request timed out"}`
|
||||
```json
|
||||
{ "error": "human-readable message", "code": "snake_case_code" }
|
||||
```
|
||||
|
||||
Status codes used across the Runtime API:
|
||||
|
||||
* **400** — Empty request body or malformed query: `{"error": "Request body is required"}` / `{"error": "...", "code": "bad_query"}`
|
||||
* **404** — Object not found (object endpoints only): `{"error": "Not found", "code": "not_found"}`
|
||||
* **500** — Lua execution error or internal error: `{"error": "<error message>"}` / `{"code": "internal_error"}`
|
||||
* **503** — Runtime API not enabled or no headless browser running: `{"error": "No headless browser running", "code": "bridge_unavailable"}`
|
||||
* **504** — Timeout exceeded: `{"error": "Request timed out", "code": "timeout"}`
|
||||
|
||||
The full set of object-API error codes: `bad_query`, `bad_field`, `unknown_operator`, `bad_limit`, `not_found`, `bridge_unavailable`, `timeout`, `internal_error`.
|
||||
|
||||
For a kubectl-style command-line client on top of these endpoints, see `sb get` in the [[CLI]] reference.
|
||||
|
||||
# How it works
|
||||
As documented in [[Architecture]], the vast majority of SilverBullet’s power is implemented in the client. However, there are use cases for programmatically accessing your space with all of SilverBullet (client’s) power.
|
||||
|
||||
Reference in New Issue
Block a user