CLI Reference

Every scratch command and its flags. A pad is referenced by name (resolved within a scanned root) or by an explicit path. Root = --dir, else $SCRATCH_DIR, else the current directory.

scratch new

scratch new "<name>" --dir <parent> [--id <id>] [--force]

Create <parent>/<slug>/ + manifest and print an onboarding prompt.

Flag	Meaning
--dir <parent>	Required — placement is always deliberate (no assumed location).
--id <id>	Associate the pad with a session/id.
--force	Overwrite an existing slug under the same parent.

scratch add

scratch add <pad> <file> [--title ..] [--desc ..] [--tag a,b] [--type note] [--group ..] [--link [--as <label>]]

Register an already-present file into the manifest with metadata.

Flag	Meaning
--title	Human label (defaults to path).
--desc	Why the file exists / what it captures.
--tag a,b	Comma-separated tags.
--type	note | snippet | output | artifact | reference (default note).
--group <name>	List files sharing a group together under a viewer header.
--link	Link an external file (outside the pad) by reference; content stays put.
--as <label>	With --link: the in-pad label (default: basename).

scratch ls

scratch ls [<pad>] [--dir <root>] [--json]

No <pad>: list pads under root. With <pad>: list its registered files. --json emits a machine-readable listing.

scratch show

scratch show <pad> [<file>] [--dir <root>] [--json]

No <file>: print the manifest. With <file>: print metadata + content.

scratch comments

scratch comments <pad> [<file>] [--dir <root>] [--json]

Read the inline comments left in the viewer back out — the human-review → agent feedback loop. Each comment prints with its quote, file:line, nearest section heading, and surrounding context, so an agent can act on it without re-reading the pad.

Flag	Meaning
<file>	Filter: exact path, glob (*.md), or case-insensitive substring.
--json	Agent-friendly output (same shape the viewer's copy-comments shortcut produces).
--related	Cover the pad's set. Each comment carries pad; --json adds pads. Works with --rm.

Comments whose quoted text can no longer be found are reported as orphaned, never dropped.

scratch rm

scratch rm <pad> [<file>] [--dir <root>] [--force]

With <file>: unregister (file left on disk). Without: delete the pad (requires --force).

scratch ui

scratch ui [<pad>] [--dir <root>] [--all] [--browser] [--install-native]

Read-only viewer: glimpse native window by default, browser fallback.

Flag	Meaning
--all	Open every pad under the root, tabbed.
--browser	Force the browser viewer (always works). It prints its URL and does not open a browser.
--install-native	Build the native host on demand (needs .NET 8 SDK).

A named pad opens with its pad set. scratch export <pad> embeds the same set.

See Viewer for details.

scratch export

scratch export [<pad>] [--dir <root>] [--all] [-o <file>] [--offline] [--theme <id>] [--mode <m>]

Write the viewer to a single HTML file (file contents embedded; highlight.js / mermaid load from a pinned CDN), openable in any browser. Default out: <pad-name>.html.

Flag	Meaning
--all	Merge every pad under the root into one file.
--offline	Inline highlight.js / mermaid / KaTeX so the page needs no network.
--theme <id>	Color theme for the exported page (see below).
--mode <m>	dark, light, or system.

Appearance

By default an export inherits the appearance from your own config (see Viewer), and the reader's remembered choice then wins — every exported page has a settings panel, and all file:// pages share one browser origin, so a theme picked in any export follows the reader into the next one.

--theme and --mode override the config and pin that axis: the exported page ignores the reader's stored preference for it, so a published page looks the same for everyone. Only the axis you pass is pinned, and pinning governs the boot value — the in-page picker still works, it just does not survive a reload.

scratch export notes --theme monokai --mode light -o public/notes.html

Theme ids: ember (default), gruvbox, catppuccin, tokyo-night, solarized, dracula, nord, rose-pine, everforest, kanagawa, one-dark, night-owl, monokai, github, ayu, vitesse, synthwave. Each has a dark and a light variant, selected by --mode. Passing an unknown id prints the full list.

scratch import

scratch import <file.html> -o <dir> [--all] [--dry-run] [--force]

The reverse of export: rebuild pad folder(s) from a scratch export page. Embedded file contents are written back to disk and scratchpad.json is regenerated from the embedded metadata — pad name and id, group layout, and each file's title, description, tags, type, group, and inline comments.

Flag	Meaning
--all	The page holds several pads (export --all): import each into <dir>/<pad-folder>/, named after the pad's original folder (slug of the name as fallback).
--dry-run	Print the plan (write/skip per file) and touch nothing.
--force	Write into a non-empty directory or over an existing pad.

scratch import notes.html -o _scratchpads/notes
scratch import all.html --all -o _scratchpads --dry-run

Notes:

• Files the export could not embed — too large or binary — are reported as skipped. Their manifest entry is kept, so the pad still lists them; the content is simply not there. Linked external files are skipped and get no entry: their src pointed outside the original pad.
• Excalidraw scenes are restored from their embedded source, and images are decoded from their base64 data URIs.
• Paths that are absolute or contain .. are rejected.
• The target must be missing or an empty directory; anything else needs --force.
• Manifest created/updated dates are set to the import time — an export does not carry the pad-level dates.

Import is a deliberate exception to the rule that the CLI never authors content: the content is your own export, and the restore is explicit.

Pad sets

Link pads that depend on each other with a top-level related list in scratchpad.json:

"related": ["client-sdk", { "pad": "../other/pad", "rel": "feeds" }]

• An entry is a pad name or a path. A name resolves among the pad's sibling folders first, then under the root. A path is relative to the pad's folder. rel is an optional label shown in the viewer.
• scratch ui <pad>, scratch export <pad> and scratch comments <pad> --related cover the set: the pad, the pads it lists, and the pads that list it. One level only, each pad once. A ref that does not resolve prints a warning and is skipped.
• The viewer gives each pad its own sidebar section, with that pad's groups, layout order and folding. A markdown link to a file registered in another pad of the set opens it there.
• scratch import does not restore related; add it again after an import.