diff --git a/website/CHANGELOG.md b/website/CHANGELOG.md index c7f77d35..651a85b1 100644 --- a/website/CHANGELOG.md +++ b/website/CHANGELOG.md @@ -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. diff --git a/website/CLI.md b/website/CLI.md index 9192031e..0851fc99 100644 --- a/website/CLI.md +++ b/website/CLI.md @@ -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 ` form). + ## `logs` Show console logs from the headless browser client. diff --git a/website/Runtime API.md b/website/Runtime API.md index 325d18d5..5bca4916 100644 --- a/website/Runtime API.md +++ b/website/Runtime API.md @@ -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": ""}` -* **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": ""}` / `{"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.