scat Quick‑Start Guide

Find, browse, and understand scripts in the catalog. For the complete workflow and terminal reference, see TUI and CLI option coverage.

0 – Prerequisites

Set the environment variable once so you never need to type --db again:

export SCAT_DB=/catalog/scat/scripts.sqlite

scat reads that catalog through a host-local copy in /dev/shm, refreshed automatically after each nightly rebuild — nothing to set up. Use --cache-dir / SCAT_CACHE_DIR to put the copy elsewhere, or --no-cache / SCAT_NO_CACHE=1 to query the shared drive directly.

Optional: config file

Instead of (or in addition to) SCAT_DB, you can point scat at a config file with --config <path> or SCAT_CONFIG for the database path, scan roots, ignore patterns, vc settings, and search bookmarks (scat search @name). See scat.example.yaml for an annotated example. CLI flags and env vars always override config-file values.

Optional: path-mapping file

scat tui --mapping <path> / SCAT_MAPPING points at a separate file that maps logical catalog paths to real filesystem paths, used by the V key to open a script’s live source. See scat-mapping.example.yaml. The same file works with scat doctor PATH --mapping <path> for host-local diagnostics; SCAT_MAPPING applies to TUI startup.

1 – Search

Find scripts by keyword

scat search "patch freeze"

Results are ranked by relevance and include path, language, owner, and purpose.

Filter by language

scat search --lang python
scat search --lang shell

Combine keyword and language filter

scat search "deploy" --lang shell

Increase the result limit (default: 50)

scat search "backup" --limit 200

Machine‑readable output (JSON / CSV)

scat search "patch freeze" --output json --fields path,owner
scat search "patch freeze" --output csv --fields path,owner,purpose

2 – Browse (TUI)

Launch the full-screen interactive browser:

scat tui

TUI keyboard shortcuts

Mouse

The TUI also responds to the mouse:

Press F2 to select arbitrary screen text using your terminal’s normal mouse drag and copy shortcut. The TUI releases the mouse and pauses background updates so the selection stays intact. Press F2 or Esc to resume. Shift+drag also bypasses mouse capture in terminals that support it.

F3 copies the selected query text (or the whole query when nothing is selected). In other panes it copies the focused preview, details, diff, or selected script path. Clicking a script path still copies that path. These actions request clipboard access via OSC 52, including over SSH; your terminal or multiplexer must allow it. The TUI reports the request, but cannot confirm that the terminal accepted it. Native terminal selection and copy provide an alternative when OSC 52 is unavailable.

Use your terminal’s paste shortcut (commonly Ctrl+Shift+V or Cmd+V) in search. On terminals supporting bracketed paste, pasted text is inserted in one operation at the cursor, replacing any selection; newlines and tabs become spaces and other control characters are removed. Pasting in other panes is ignored with a hint to focus search. On terminals without bracketed paste, input arrives as ordinary keystrokes, so paste single-line text into search. Ctrl+C quits the app; use your terminal’s copy shortcut to copy native selections. Esc clears a query selection before exiting search.

The details pane shows metadata, checkout state, source preview, and related or dependent scripts for the highlighted result. Press Enter on a result to open a full script detail view with tags, entry points, warnings, checkout rows, dependency summary, folder siblings, and source preview.

3 – Inspect a script

Show full details for a known script path:

scat show /catalog/scripts/patch_check.py

JSON output

scat show /catalog/scripts/patch_check.py --output json

Folder context

Opt-in fields list the script’s parent directory and the other scripts indexed in the same folder:

scat show /catalog/scripts/patch_check.py --fields folder,siblings

4 – Dependencies

List what a script depends on and what depends on it:

scat deps /catalog/scripts/patch_check.py

5 – Script diff

Compare a cataloged script against its checked-out vc copy or an explicit file.

vc contract: scat diff is read-only. It never writes to vc-managed DEVELOP or ARCHIVE directories.

Compare active catalog script with its most-recent vc checkout

scat diff /catalog/foo/bar.py

The catalog’s stored content is shown as --- and the most-recent indexed DEVELOP revision is shown as +++. If multiple DEVELOP revisions exist, the one with the latest timestamp is used automatically.

Compare against a specific checkout or archive file

# DEVELOP checkout (filename carries timestamp and user)
scat diff /catalog/foo/bar.py --against /catalog/foo/DEVELOP/bar.py_20240510_103044_alice

# ARCHIVE copy (filename carries timestamp only)
scat diff /catalog/foo/bar.py --against /catalog/foo/ARCHIVE/bar.py_20240510_103044

--against points to a file on disk, unlike scat catalog diff --against which points to a database snapshot.

Select an indexed revision

scat diff /catalog/foo/bar.py --revision-type ARCHIVE

Select DEVELOP, WORKING, ARCHIVE or ROLLBACK; optionally narrow with --revision-timestamp, or --revision-user for DEVELOP/ROLLBACK checkouts. Use scat status /catalog/foo/bar.py to inspect available revisions.

Compare any two explicit files

No catalog access is needed; --db / SCAT_DB is optional for this mode:

scat diff --old old_version.py --new new_version.py

Machine-readable JSON output

scat diff /catalog/foo/bar.py --json

The JSON output includes:

Each element in lines has kind (context, delete, or insert) and content.

Error hints

6 – Catalog statistics

scat catalog stats

Shows total script count, breakdown by language, and breakdown by owner. When vc revision data has been indexed and vc is configured, it also prints revision statistics for DEVELOP/ARCHIVE entries.

scat catalog stats --json

JSON output includes the same revision counters under a revisions key when that data is available.

7 – Index information

Check when the catalog was last built and which schema version is in use:

scat catalog info

Shared catalog schema upgrades

The current catalog schema is v14. A client reads exactly the schema it was built for, so a schema change is a coordinated upgrade of the publisher, the catalog and the clients. scat catalog info prints the catalog’s and the client’s schema versions and a compatibility verdict even for a catalog the client refuses, and exits non-zero when it is unreadable.

The error says which side is behind:

• the catalog is older than this scat — the publisher must upgrade scat and rebuild: scat --config /path/to/site.yaml catalog build.
• this scat is older than the catalog — upgrade scat on this host.

Ordinary read-only clients never rebuild the shared catalog. The decision, supported combinations, rollout and rollback steps are in COMPATIBILITY.md.

8 – Common CLI patterns

List all Python scripts

scat search --lang python --limit 1000

Find scripts owned by a specific user

scat search --owner alice@example.com --limit 1000

Check whether a specific script exists

scat show /catalog/scripts/my_script.py && echo "found" || echo "not found"

Export up to 10,000 matching scripts to JSON

scat search --output json --limit 10000 > catalog.json

Pipe results to grep

scat search "deploy" | grep -F ".sh"

9 – Troubleshooting

Use scat doctor without a working catalog for read-only host diagnostics. For a specific script, include its path and optionally query local RPM metadata:

scat doctor --json
scat doctor /catalog/scripts/patch_check.py --mapping mapping.yaml --rpm --json

10 – Getting help

scat --help
scat doctor --help
scat search --help
scat show --help
scat deps --help
scat diff --help
scat catalog stats --help
scat catalog info --help
scat catalog diff --help
scat tui --help