142 lines
4.7 KiB
Markdown
142 lines
4.7 KiB
Markdown
---
|
||
tags: maturity/experimental
|
||
references:
|
||
- bin/sb/src/cli.rs
|
||
- bin/sb/src/commands/mod.rs
|
||
- bin/sb/src/main.rs
|
||
---
|
||
|
||
> **note** This is **not** the server
|
||
> `sb` is the optional **CLI client**, it talks to an already-running SilverBullet instance over HTTP. If you’re looking for the actual server binary, that’s [[Install/Binary]] (`silverbullet`), not this. You do not need `sb` to use SilverBullet.
|
||
|
||
The SilverBullet CLI is a companion command-line tool for interacting with a running SilverBullet instance from your terminal. It communicates with the server via the [[Runtime API]], letting you evaluate Lua expressions, run scripts, open an interactive REPL, tail logs, and more — without touching a browser.
|
||
|
||
# Installation
|
||
The CLI binary (`sb`) is available alongside the server binary on the [GitHub releases page](https://github.com/silverbulletmd/silverbullet/releases) (or the [edge](https://github.com/silverbulletmd/silverbullet/releases/tag/edge) build). Download the version matching your platform.
|
||
|
||
Once installed, it can self-update:
|
||
```bash
|
||
sb upgrade # latest stable release
|
||
sb upgrade-edge # latest edge (main branch) build
|
||
```
|
||
|
||
# Configuring spaces
|
||
Before using the CLI, connect it to a SilverBullet instance. The CLI stores space configurations in `~/.config/silverbullet/config.json` (respects `XDG_CONFIG_HOME`).
|
||
|
||
## Adding a space
|
||
```bash
|
||
sb space add
|
||
```
|
||
This interactive wizard will prompt for:
|
||
1. A **name** for the space (alphanumeric and hyphens)
|
||
2. The **URL** of your SilverBullet server
|
||
3. **Authentication** method ([[Install/Configuration#Authentication|token]], username/password, or none)
|
||
|
||
## Listing and removing spaces
|
||
```bash
|
||
sb space list
|
||
sb space remove <name>
|
||
```
|
||
|
||
# Global flags
|
||
These flags are available on all commands that connect to a space:
|
||
|
||
| Flag | Description |
|
||
|---|---|
|
||
| `-s, --space <name>` | Select a space by name (auto-selected if only one is configured) |
|
||
| `--url <url>` | Connect directly to a URL (bypasses space config) |
|
||
| `--token <token>` | Authentication token (use with `--url`) |
|
||
| `-t, --timeout <seconds>` | Request timeout (default: 30) |
|
||
|
||
# Commands
|
||
Note that the first call may take a few seconds, since the [[Runtime API]] will spin up a headless Chromium instance and need to perform an initial index for the first call.
|
||
|
||
## `lua <expression>`
|
||
Evaluate a single Lua expression and print the result.
|
||
|
||
```bash
|
||
sb lua "1 + 1"
|
||
# => 2
|
||
|
||
sb lua "editor.getCurrentPage()"
|
||
# => "index"
|
||
```
|
||
|
||
## `lua-script [file]`
|
||
Execute a multi-line Lua script from a file or stdin.
|
||
|
||
```bash
|
||
sb lua-script myscript.lua
|
||
|
||
# Or pipe from stdin:
|
||
echo 'local x = 40; return x + 2' | sb lua-script
|
||
```
|
||
|
||
## `repl`
|
||
Open an interactive Lua REPL with multi-line support.
|
||
|
||
```bash
|
||
sb repl
|
||
```
|
||
|
||
Special commands inside the REPL:
|
||
* `.exit` or `Ctrl-D` — exit
|
||
* `.script` / `.end` — enter/exit multi-line script mode
|
||
* `.timeout <seconds>` — change request timeout
|
||
|
||
The REPL automatically detects incomplete expressions (unclosed brackets, blocks) and waits for more input.
|
||
|
||
## `logs`
|
||
Show console logs from the headless browser client.
|
||
|
||
```bash
|
||
sb logs # last 100 entries
|
||
sb logs -n 20 # last 20 entries
|
||
sb logs -f # follow (tail) mode
|
||
```
|
||
|
||
| Flag | Description |
|
||
|---|---|
|
||
| `-n, --lines <int>` | Number of entries (default: 100) |
|
||
| `-f, --follow` | Continuously stream new log entries |
|
||
|
||
## `screenshot [file]`
|
||
Capture a PNG screenshot of the headless client viewport.
|
||
|
||
```bash
|
||
sb screenshot page.png # save to file
|
||
sb screenshot > page.png # or pipe to stdout
|
||
```
|
||
|
||
## `version`
|
||
Print the installed CLI version.
|
||
|
||
## `upgrade` / `upgrade-edge`
|
||
Self-update the CLI binary to the latest stable or edge release.
|
||
|
||
# Authentication
|
||
The CLI supports three authentication methods, configured per-space during `space add`:
|
||
|
||
* **Token** — sends an `Authorization: Bearer <token>` header. Use this with `SB_AUTH_TOKEN` on a [[Space Manager#Single-space mode|single-space]] server, or with a per-account [[Space Manager#API tokens|API token]] on an accounts-based server.
|
||
* **Password** — authenticates via `POST /.auth` (username/password), then uses the returned session cookie. Use this with `SB_USER` on a single-space server, or with an account username/password on a space you’re a member of.
|
||
* **None** — no authentication (for local or trusted-network setups, or public spaces).
|
||
|
||
Credentials are encrypted at rest using AES-256-GCM with PBKDF2 key derivation.
|
||
|
||
# Examples
|
||
|
||
Query your space for recent pages:
|
||
```bash
|
||
sb lua 'query[[from tags.page order by lastModified desc limit 5 select name]]'
|
||
```
|
||
|
||
Run a script that lists all tasks:
|
||
```bash
|
||
echo 'return query[[from tags.task where not done select ref, name]]' | sb lua-script
|
||
```
|
||
|
||
Tail logs while debugging:
|
||
```bash
|
||
sb logs -f
|
||
```
|