saterminal

SAT practice that stays on your computer. The app ships with a compressed question bank (3K+ questions, ~2MB), works without an account or network connection, and records progress in a local SQLite database (stored in ~/.saterminal).

If you ever need to study one question at a time, you shouldn't be downloading worksheets or navigating a clunky and ever-changing website. You also don't need to see question metadata while reading questions (somehow this is an issue on many SAT practice websites).

Get started

npm install -g saterminal

The npm package installs a standalone executable for the current operating system and architecture. Bun is not required to run it.

OR

brew install sreyassabbani/tap/saterminal

Homebrew installs the same standalone executable.

Now, you can run sat anywhere.

Local data

The first launch asks before creating ~/.saterminal.

• sat.db contains some settings & user history.
• .ignore keeps the generated cache out of supporting editor file pickers.
• preferences.json & preferences.schema.json (you can manipulate these files via the TUI or CLI as well)
• cache/question-bank.json is the local unzipped question bank.

Deleting ~/.saterminal resets local progress: no cloud account, sync service, server, or auth layer.

Useful commands

Running sat opens the interactive study home. Reports use the richer terminal layout by default; no -p flag is necessary.

sat                              # open practice, review, progress, or settings
sat review                       # revisit eligible missed and corrected questions
sat weak                         # rank the skills that need attention
sat stats                        # accuracy, timing, streak, and activity
sat history                      # recent question outcomes
sat history --wrong --since 2w
sat focus                        # inspect the active focus
sat config                       # inspect local preferences

Every report also supports:

sat stats --plain    # compact, stable text
sat stats --json     # machine-readable output
sat stats --no-color
NO_COLOR=1 sat weak

Use sat <command> --help for command-specific filters.

Review spacing

A missed or corrected question enters sat review only after both default spacing requirements are met:

• at least X days have passed since its latest answer;
• at least Y answer events were recorded after that answer.

X and Y are defined in preferences.json, and are defaulted to 7 and 100, respectively. This prevents an immediate retry from masquerading as durable recall. Change either threshold with:

sat config set --minimum-days 14
sat config set --minimum-answers-after 200
sat config set --minimum-days 14 --minimum-answers-after 200
sat config reset

Result detail

Choose how much learner-facing context appears after an answer:

sat config set --result-detail brief     # time
sat config set --result-detail standard  # time and difficulty (default)
sat config set --result-detail detailed  # time, difficulty, and taxonomy

The verdict, answer choices, and explanation remain visible at every level. Internal question IDs stay available through sat show, not the result screen.

Interactive keys

The footer always shows the keys available on the current screen. The common ones are:

| Key | Action | | --- | --- | | j / k, arrows | Move through focus options and answers; scroll the active review pane | | Tab, left/right | Move between focus groups or question/answer panes | | Space | Toggle a focus option; pause a running question timer | | Enter | Start, submit, continue, or open a history item | | A–D | Select an answer directly | | x | Cross out or restore the highlighted answer | | Ctrl + u / Ctrl + d | Move up / down half a page in history | | [ / ], Page Up/Down | Scroll the active question, answer, or explanation pane | | t | Show or hide the timer while actively answering | | m | Return to the study home | | f / h / s / p | Focus / history / summary / practice, outside an active question or its result | | q | Quit |

Questions containing HTML tables can be opened on Practice SAT with o; the rest of the practice flow remains local.

Development

Enable the development shell once with direnv allow or prefix individual commands with nix develop -c. Install dependencies and build the current checkout:

bun install
bun run build
./dist/sat

Keep the available executables intentionally distinct:

| Invocation | Meaning | | --- | --- | | sat | Latest installed release | | ./dist/sat | Compiled snapshot of the current unreleased checkout | | ./result/bin/sat | Nix-built current checkout |

Avoid bun link for normal development: it makes sat resolve to the checkout and removes the useful release-versus-development distinction. Linking is only useful when specifically testing package installation or the package's bin entry.

Build artifacts

bun run build replaces dist/sat with a compiled, minified Bun executable for the current machine. Use it for normal testing of a non-tagged tip version. It bundles the application, OpenTUI's native renderer, its other dependencies, and the Bun runtime.

Tagged releases cross-compile the same entrypoint for macOS, glibc Linux, musl Linux, and Windows on supported x64 and ARM64 architectures. npm installs only the platform package matching the user's machine.

Use nix build to build the reproducible Nix package:

nix build
./result/bin/sat --version
nix run . -- --help

The Nix package does not use dist/sat. It independently compiles result/bin/sat as a standalone executable and does not ship the source tree or node_modules.

Maintain the question bank

Refresh the bundled bank for a future release with:

nix develop -c bun run update-bank

This is the only normal source workflow that contacts the upstream Practice SAT service. It downloads, normalizes, and writes data/question-bank.json.zst.

Verify changes

Verifying once before publishing is enough.

nix develop -c bun run typecheck
nix develop -c bun test
nix develop -c bun run build
./dist/sat --help
nix build
./result/bin/sat --version
nix run . -- --version

When bun.lock changes, regenerate the committed Nix dependency expression before building:

nix develop -c bun run nix:deps

Publishing

CD for npm is set up with .github/workflows/publish.yml, so release by creating a SemVer tag:

bun pm version <increment>

The increment follows SemVer: major, minor, or patch. This commits the version change and creates its annotated v… tag. The version lifecycle keeps every platform package and the dispatcher's optional dependencies on that same version.

Push the commit and its release tag together:

git push --follow-tags

The platform packages need one-time npm setup before the first binary release. Add a short-lived granular publishing token as the NPM_TOKEN repository secret for that release. After the workflow creates the packages, configure publish.yml as the trusted publisher for each platform package on npm and delete the secret. Later releases use npm's GitHub OIDC publishing.