runtime website docs

This commit is contained in:
Zef Hemel
2026-05-14 17:04:22 +02:00
parent f89fae92c9
commit bf7831ebba
3 changed files with 129 additions and 8 deletions
+3 -2
View File
@@ -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.
+43
View File
@@ -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
View File
@@ -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.