CLI Reference

`sideshow`

version: 0.1.2

Git-backed event-sourced document database CLI

Usage: sideshow [FLAGS] <SUBCOMMAND>

Global Flags

`--json`

Emit machine-readable JSON output for document, event, snapshot, and auth commands.

`--help`

Print help information.

`--refstore <backend>`

Native document commands resolve the refstore in this precedence order:

--refstore subprocess|github
SIDESHOWDB_REFSTORE=subprocess|github
.sideshowdb/config.toml
built-in default: subprocess

Invalid backend names fail before document state is mutated.

Selecting --refstore github also requires --repo owner/name and resolvable GitHub credentials. Run 'sideshow gh auth login' to provide a personal access token.

Choices:

subprocess
github

Default: subprocess

Environment Variable: SIDESHOWDB_REFSTORE

`--repo <owner/name>`

GitHub repository (owner/name) for --refstore github.

Environment Variable: SIDESHOWDB_REPO

`--ref <refname>`

Git ref used by --refstore github. Defaults to refs/sideshowdb/documents.

Default: refs/sideshowdb/documents

Environment Variable: SIDESHOWDB_REF

`--api-base <url>`

GitHub REST API base URL. Defaults to https://api.github.com .

Environment Variable: SIDESHOWDB_API_BASE

`--credential-helper <helper>`

Credential source for --refstore github. One of: auto, env, gh, git.

Choices:

auto
env
gh
git

Default: auto

Environment Variable: SIDESHOWDB_CREDENTIAL_HELPER

`sideshow version`

Usage: sideshow version
Source code: src/cli/version

Print the product banner and package version.

Examples

$ sideshow version

null

`sideshow help`

Usage: sideshow help
Source code: src/cli/help

Print top-level help, or help for a command path such as 'sideshow help doc put'.

Examples

$ sideshow help

null

$ sideshow help doc put

null

`sideshow doc`

Usage: sideshow doc <SUBCOMMAND>
Source code: src/cli/doc

Document commands run against the current working directory's Git repository unless the embedding test harness passes a repository path directly.

Backend selection applies to native document commands. The browser WASM runtime has its own in-WASM MemoryRefStore default and optional TypeScript host store.

`sideshow doc put`

Usage: sideshow doc put [FLAGS]
Source code: src/cli/doc/put

Create or replace a document version.

Flags

`--namespace <namespace>`

Logical namespace. Defaults to default.

`--type <type>`

Document type. If omitted, the JSON payload may provide it.

`--id <id>`

Document id. If omitted, the JSON payload may provide it.

`--data-file <path>`

--data-file wins when both stdin and --data-file are present.

A missing or unreadable --data-file path returns exit code 1, writes a --data-file error to stderr, and does not mutate document state.

Examples

$ echo '{"title":"From stdin"}' | sideshow --json doc put --type note --id stdin-demo

null

$ sideshow --json doc put --type note --id file-demo --data-file payload.json

null

`sideshow doc get`

Usage: sideshow doc get [FLAGS]
Source code: src/cli/doc/get

Read the current document value, or a specific historical version.

Flags

`--namespace <namespace>`

Logical namespace. Defaults to default.

`--type <type>`

Document type.

`--id <id>`

Document id.

`--version <version>`

Version id returned by a prior put or history call.

Examples

$ sideshow --json doc get --type note --id file-demo

null

`sideshow doc list`

Usage: sideshow doc list [FLAGS]
Source code: src/cli/doc/list

List documents in the document section.

Flags

`--namespace <namespace>`

Filter to one namespace.

`--type <type>`

Filter to one document type.

`--limit <count>`

Maximum number of items to return.

`--cursor <cursor>`

Cursor returned by a previous paged response.

`--mode <mode>`

summary returns identity/version metadata; detailed includes document data.

Choices:

summary
detailed

Default: summary

Examples

$ sideshow --json doc list --type note --mode summary

null

`sideshow doc delete`

Usage: sideshow doc delete [FLAGS]
Source code: src/cli/doc/delete

Delete the latest reachable document value.

Flags

`--namespace <namespace>`

Logical namespace. Defaults to default.

`--type <type>`

Document type.

`--id <id>`

Document id.

Examples

$ sideshow --json doc delete --type note --id file-demo

null

`sideshow doc history`

Usage: sideshow doc history [FLAGS]
Source code: src/cli/doc/history

List historical document versions newest-first.

Flags

`--namespace <namespace>`

Logical namespace. Defaults to default.

`--type <type>`

Document type.

`--id <id>`

Document id.

`--limit <count>`

Maximum number of versions to return.

`--cursor <cursor>`

Cursor returned by a previous paged response.

`--mode <mode>`

summary returns identity/version metadata; detailed includes historical document data.

Choices:

summary
detailed

Default: summary

Examples

$ sideshow --json doc history --type note --id file-demo --mode detailed

null

`sideshow event`

Usage: sideshow event <SUBCOMMAND>
Source code: src/cli/event

Event commands run against refs/sideshowdb/events in the subprocess refstore. Use event append to write one single-stream batch and event load to replay stream events.

`sideshow event append`

Usage: sideshow event append [FLAGS]
Source code: src/cli/event/append

Append a JSONL or JSON event batch to one stream.

Flags

`--namespace <namespace>`

Logical namespace.

`--aggregate-type <aggregate_type>`

Aggregate type.

`--aggregate-id <aggregate_id>`

Aggregate id.

`--expected-revision <revision>`

Required current stream revision. Omit to append without revision check.

`--format <format>`

Input format for the append payload.

Choices:

jsonl
json

Default: jsonl

`--data-file <path>`

--data-file wins when both stdin and --data-file are present.

A missing or unreadable --data-file path returns exit code 1, writes a --data-file error to stderr, and does not mutate event state.

Examples

$ sideshow --json event append --namespace default --aggregate-type issue --aggregate-id issue-1 --expected-revision 0 --format jsonl < events.jsonl

null

$ sideshow --json event append --namespace default --aggregate-type issue --aggregate-id issue-1 --format json --data-file batch.json

null

`sideshow event load`

Usage: sideshow event load [FLAGS]
Source code: src/cli/event/load

Load events for one stream in append order.

Flags

`--namespace <namespace>`

Logical namespace.

`--aggregate-type <aggregate_type>`

Aggregate type.

`--aggregate-id <aggregate_id>`

Aggregate id.

`--from-revision <revision>`

Load events from this one-based revision onward.

Examples

$ sideshow --json event load --namespace default --aggregate-type issue --aggregate-id issue-1 --from-revision 2

null

`sideshow snapshot`

Usage: sideshow snapshot <SUBCOMMAND>
Source code: src/cli/snapshot

Snapshot commands run against refs/sideshowdb/snapshots in the subprocess refstore. Use snapshot put to store a revision-addressed state snapshot and snapshot get/list to read snapshots.

`sideshow snapshot put`

Usage: sideshow snapshot put [FLAGS]
Source code: src/cli/snapshot/put

Store one snapshot for a stream revision.

Flags

`--namespace <namespace>`

Logical namespace.

`--aggregate-type <aggregate_type>`

Aggregate type.

`--aggregate-id <aggregate_id>`

Aggregate id.

`--revision <revision>`

Snapshot revision (must be > 0).

`--up-to-event-id <event_id>`

Event id included by this snapshot.

`--state-file <path>`

Read required snapshot state JSON from a file instead of stdin.

`--metadata-file <path>`

Read optional snapshot metadata JSON from a file.

Examples

$ sideshow --json snapshot put --namespace default --aggregate-type issue --aggregate-id issue-1 --revision 5 --up-to-event-id evt-5 --state-file snapshot-state.json

null

`sideshow snapshot get`

Usage: sideshow snapshot get [FLAGS]
Source code: src/cli/snapshot/get

Get the latest snapshot or one at-or-before a revision.

Flags

`--namespace <namespace>`

Logical namespace.

`--aggregate-type <aggregate_type>`

Aggregate type.

`--aggregate-id <aggregate_id>`

Aggregate id.

`--latest`

Get the highest stored snapshot revision for the stream.

`--at-or-before <revision>`

Get the highest snapshot revision less than or equal to this revision.

Examples

$ sideshow --json snapshot get --namespace default --aggregate-type issue --aggregate-id issue-1 --latest

null

$ sideshow --json snapshot get --namespace default --aggregate-type issue --aggregate-id issue-1 --at-or-before 10

null

`sideshow snapshot list`

Usage: sideshow snapshot list [FLAGS]
Source code: src/cli/snapshot/list

List snapshot metadata newest-first for one stream.

Flags

`--namespace <namespace>`

Logical namespace.

`--aggregate-type <aggregate_type>`

Aggregate type.

`--aggregate-id <aggregate_id>`

Aggregate id.

Examples

$ sideshow --json snapshot list --namespace default --aggregate-type issue --aggregate-id issue-1

null

`sideshow auth`

Usage: sideshow auth <SUBCOMMAND>
Source code: src/cli/auth

Auth commands manage credentials stored under ~/.config/sideshowdb/hosts.toml (mode 0600).

Tokens are never echoed to the terminal and are never written to argv. Use 'sideshow gh auth login' to authenticate to github.com.

`sideshow auth status`

Usage: sideshow auth status
Source code: src/cli/auth/status

Show authenticated hosts and the active credential source for each.

Examples

$ sideshow auth status

null

$ sideshow --json auth status

null

`sideshow auth logout`

Usage: sideshow auth logout [--host <hostname>]
Source code: src/cli/auth/logout

Remove stored credentials for one or all hosts.

Flags

`--host <hostname>`

Logout of a single host. Omit to remove every entry from hosts.toml.

Examples

$ sideshow auth logout --host github.com

null

$ sideshow auth logout

null

`sideshow gh`

Usage: sideshow gh <SUBCOMMAND>
Source code: src/cli/gh

GitHub-specific commands.

`sideshow gh auth`

Usage: sideshow gh auth <SUBCOMMAND>
Source code: src/cli/gh/auth

GitHub authentication commands.

`sideshow gh auth login`

Usage: sideshow gh auth login [--with-token] [--skip-verify]
Source code: src/cli/gh/auth/login

Interactive mode prompts for a token on /dev/tty with echo disabled and reads it without writing it to terminal history.

--with-token reads the token from stdin (CI-friendly). The token is trimmed; any whitespace inside the value is rejected.

Required PAT scopes: 'repo' (read+write to git database), or fine-grained PAT with Contents: Read and write on the target repository.

Flags

`--with-token`

Read the token from stdin instead of prompting interactively.

`--skip-verify`

Persist the token without calling GET /user to verify it.

Examples

$ echo $GITHUB_PAT | sideshow gh auth login --with-token

null

$ sideshow gh auth login

null

`sideshow gh auth status`

Usage: sideshow gh auth status
Source code: src/cli/gh/auth/status

Show github.com authentication status.

`sideshow gh auth logout`

Usage: sideshow gh auth logout
Source code: src/cli/gh/auth/logout

Remove stored github.com credentials.

Last update at: 2026/05/02 09:52:30

On this page