bsj

BlueScreen Journal is an encrypted, local-first journaling app for macOS terminals. It is built for people who want the focused feel of an old DOS word processor, but with modern safety features: encrypted storage, append-only history, encrypted drafts, encrypted backups, and encrypted sync.

The product goal is narrow on purpose: launch, unlock once, and start writing immediately in a blue-screen full-screen editor that feels like a dedicated writing appliance.

At a glance

write-first terminal experience with a consistent DOS-style workspace
encrypted vault, drafts, backups, and sync blobs
append-only revisions and integrity verification
menu-driven discoverability so new users are not blocked by key memorization
local-first design with encrypted folder sync plus S3/WebDAV and direct Google Drive/Dropbox API connectors
optional AI summary and reflective coach mode (off by default)

New in v2.2.3

fixed the installer Launch BlueScreen Journal here now path when the installer is started with curl | bash
the post-install same-terminal handoff now allocates a clean PTY before entering the blue-screen TUI
installer QA now exercises the real piped-launch + option 1 path with a TUI smoke check instead of only asserting --version
the stable line stays focused on release durability and first-run trust, not feature churn

Screenshots

Writing View	Search View

Full-screen editor with persistent menu and command strip.	Global search with filters and quick-open results.
Calendar View	Index View

Month grid with saved-day highlights and fast date jump.	Real timeline with entry previews and conflict indicators.

Why bsj exists

Most journaling tools force one of two bad tradeoffs:

modern note apps give you sync and search, but pull you into a GUI workflow full of chrome
plaintext file workflows keep control local, but leave sensitive writing exposed on disk and in cloud folders

bsj is designed to avoid both.

It gives you:

a keyboard-only writing flow with a persistent command strip and nostalgic 80x25 screen discipline
encrypted-at-rest journal content, drafts, backups, and sync blobs
append-only revisions so intentional saves create history instead of overwriting it
menu-driven discovery so the app still feels learnable without memorizing every function key
real editor commands for line movement, stamps, and structural writing work
in-product review and admin surfaces so daily use stays inside the TUI

Product snapshot

platform: macOS
interface: full-screen Rust TUI in Terminal.app and iTerm2
visual direction: royal-blue background, white monospaced text, classic DOS-era workspace
storage model: local-first encrypted vault on disk
sync model: encrypted folder sync, plus S3/WebDAV and direct Google Drive/Dropbox API backends
history model: append-only revisions plus encrypted per-date autosave drafts
search model: in-memory index after unlock, with no plaintext search index on disk

Documentation by task

Goal	Read this first
Install and get writing quickly	README install section, What’s New, Cheat Sheet, Quickstart, Setup Guide
Understand product capabilities	Product Guide, Datasheet, Compare
Understand the nostalgia UX contract	Nostalgia Guardrails, Terminal Guide
Resolve install/runtime issues	Troubleshooting, Terminal Guide, Support
Operate sync/backup safely	Sync Guide, Backup Restore, Privacy
Configure and tune behavior	Settings Guide, config.example.json
Package or distribute releases	Distribution Guide, Release Certification, Maintenance Baseline, Release Notes

Turnkey install

Public one-line install:

curl -fsSL https://raw.githubusercontent.com/Awassee/bluescreenjournal/main/install.sh | bash

Pin a specific release:

curl -fsSL https://raw.githubusercontent.com/Awassee/bluescreenjournal/main/install.sh | bash -s -- --version v2.2.3

Install from source instead of the prebuilt release:

curl -fsSL https://raw.githubusercontent.com/Awassee/bluescreenjournal/main/install.sh | bash -s -- --source

Local install from a checkout:

./install.sh

Uninstall options:

./install.sh --uninstall
./install.sh --factory-reset

Installer troubleshooting options:

./install.sh --doctor
./install.sh --repair-path
./install.sh --about

./install.sh now opens an interactive installer menu in a local terminal session, including uninstall and full factory-reset actions.

What the installer does:

first install defaults to the latest public prebuilt release
rerun on a machine that already has bsj defaults to latest main source build (so updates include newest commits)
installs bsj
installs bundled docs and the man page
installs shell completions for Bash, Zsh, and Fish
prints the exact PATH fix if your install directory is not already on PATH
prints installed bsj --version and the active bsj path resolved from PATH
verifies the downloaded archive against its .sha256 file when available

Default prebuilt install path:

~/.local/bin/bsj

First five minutes

Run bsj
If this is the first launch, complete the in-product setup wizard:
- vault path
- passphrase
- passphrase confirmation
- optional legacy epoch date (kept in vault metadata for older imports)
Start typing immediately into today's entry
Press F2 to create your first encrypted saved revision
Reopen with bsj or jump to another date with bsj open YYYY-MM-DD

Default vault path:

~/Documents/BlueScreenJournal

What using it feels like

The live screen is intentionally constrained to a centered DOS-style 80x25 workspace, even on a large terminal.

The layout is stable:

header: product title, date/time, entry number, lock state, verify state, save state
menu bar: FILE, EDIT, SEARCH, GO, TOOLS, SETUP, HELP
body: text editor plus optional Reveal Codes line and Closing Thought line
footer: always-visible function-key command strip

The app is direct by design:

launch into the editor, not a dashboard
type without reaching for the mouse
save milestones intentionally
let encrypted drafts protect the gap between saves
navigate by date, index, or search when needed
lock the vault when you step away

Core features and why they matter

Feature	What it does	User value
Full-screen editor	Opens directly into the current entry	Removes friction between launch and writing
Menu-driven TUI	Keeps all major commands discoverable in-product	Makes the app usable without memorizing everything
Writing commands	Adds duplicate/move/delete line tools plus date/time, divider, stats, and metadata stamps	Makes the editor feel like a complete journaling workstation
Append-only revisions	Every manual save creates a new revision file	Preserves history and supports safer recovery
Encrypted autosave drafts	Autosaves per-date draft state without making revision spam	Protects unsaved work without plaintext leakage
Crash recovery	Prompts to recover a newer draft	Prevents accidental loss after interruption
Entry numbers	Advances `ENTRY NO.` with each saved revision and shows the next serial on a fresh page	Makes same-day saves and clean next-entry flow visible at a glance
Real index and calendar	Browse saved dates as a journal, not just as files	Faster recall and better chronological navigation
Favorite and random navigation	Jump by favorites, recents, and random saved entries	Makes larger journals easier to roam
In-entry find and replace	Incremental find and retro `Y/N/A/Q` replace flow	Keeps editing fast inside the writing surface
In-entry spellcheck	Suggests corrections, typo auto-fix, and temporary session ignore words	Catches low-signal mistakes without breaking writing momentum
Global search	Searches saved entries after unlock without disk plaintext index	Fast retrieval without leaving search residue on disk
Search presets and cache status	Adds today/month/all scopes plus encrypted cache inspection	Makes search faster to aim and easier to trust
Encrypted sync	Syncs encrypted revision blobs to folder, S3, WebDAV, Google Drive API, or Dropbox API targets	Lets you use cloud storage without uploading plaintext
Provider presets	Auto-detects Google Drive, Dropbox, OneDrive, iCloud Drive, and Box Drive folders	Makes mainstream cloud setup one command/menu step instead of manual path hunting
Cloud recovery status	Shows upload/download queues plus verify status in `TOOLS -> Cloud Status` and `bsj cloud status`	Makes recovery readiness visible before something goes wrong
Pull-only cloud recovery	Pulls missing encrypted blobs from remote without uploading local-only data (`TOOLS -> Recover From Cloud`, `bsj cloud recover`)	Safely rebuilds a machine after loss while preserving remote history
Integrity verify	Checks revision hashchains	Detects missing or tampered history
Review and dashboard surfaces	Show streaks, mood distribution, backup policy, sync preview, and doctor output	Keeps operational awareness inside the product
Insights Center	Adds ten actionable reports (momentum, readiness, volume, streak, metadata trends, cadence gaps, conflict/backup risk)	Turns journal history into immediate writing and safety feedback from menus
Reveal Codes	Shows metadata inline in a retro-friendly way	Gives structural visibility without cluttering normal view
Opening Line Template	Auto-seeds a configurable header line on blank entry pages	Gives each entry a consistent, personal starting line
Closing Thought	Dedicated final line field for each entry	Encourages deliberate endings and cleaner exports
Optional AI reflection	Adds summary and guided prompts on demand from `TOOLS`	Offers an alternate entry path without changing default writing flow
Encrypted backup and restore	Creates encrypted snapshots with retention support	Gives offline recovery without plaintext archives
Lock command	Wipes unlocked state and returns to passphrase prompt	Safer on visible or shared terminals

Everyday workflow

Write

bsj launches the TUI on the current date
type immediately into the editor
F2 or FILE -> Save Entry creates a new encrypted revision
type **save** on its own line and press Enter to save and open the next same-day entry
Alt+N opens the next blank day when you want to move forward in time
autosave maintains an encrypted draft every few seconds

Move through time

F3 or GO -> Open Calendar opens the month grid for deliberate old-entry browsing
F7 or GO -> Index Timeline lists existing saved entries when you want archive/history view
bsj open YYYY-MM-DD launches directly into a date from the CLI

Find things

F4 or EDIT -> Find in Entry searches inside the current entry
F6 or EDIT -> Replace in Entry runs replace confirmation in a retro style
Ctrl+Shift+F or TOOLS -> Spellcheck Entry opens correction picker
TOOLS -> Auto-Fix Common Typos applies safe typo corrections
bsj spellcheck --date YYYY-MM-DD checks one saved entry from CLI
bsj spellcheck --range last7 --count-only gives fast typo-count signal
F5 or SEARCH -> Search Vault searches across saved entries
SEARCH -> Saved Presets reopens named query+range presets
in Search overlay: Ctrl+Shift+B saves current query as a preset and Ctrl+1..9 loads preset slots
bsj search "query" --from YYYY-MM-DD --to YYYY-MM-DD searches from the CLI
bsj search "query" --range last7 --summary prints quick aggregate signal for recent entries
bsj search "query" --match-mode any|all|phrase --sort relevance --hits-per-entry 5 enables richer retrieval control
bsj search --preset "Weekly Review" runs a saved preset
bsj search --list-presets lists saved presets
bsj search "query" --save-preset "Name" saves and runs a preset in one command
bsj search --delete-preset "Name" removes a saved preset
bsj review --range last30 --goal 750 --json exports range-bounded review metrics plus word-goal hit rate
bsj timeline --summary --format json outputs aggregate timeline analytics
bsj timeline --group-by week --range last30 rolls entries into weekly groups
TOOLS -> Insights Center opens ten focused writing/safety reports without leaving the TUI flow
bsj timeline --save-preset "Recent Work" --query ship --tag work stores a reusable timeline filter
bsj timeline --preset "Recent Work" applies a saved timeline preset
bsj prompts pick --category reflection --json returns deterministic prompt payloads

Optional AI reflection mode (off by default)

TOOLS -> AI Summary (Optional) summarizes the current in-memory entry context
TOOLS -> AI Coach Mode (Optional) opens guided day-reflection prompts and inserts your Q/A transcript back into the editor
Ctrl+Shift+A opens AI Coach quickly
bsj ai summary --date YYYY-MM-DD prints a concise summary in the terminal
bsj ai coach --date YYYY-MM-DD --questions 5 prints reflective prompts in the terminal
remote AI is opt-in only: set BSJ_AI_ENABLE_REMOTE=1 and BSJ_OPENAI_API_KEY (or OPENAI_API_KEY)
when remote is not configured, bsj falls back to local heuristic summary/prompt generation

Protect and move data

F8 or TOOLS -> Sync Vault syncs encrypted blobs
SETUP -> Cloud Provider Setup handles both:
- folder sync detection for Google Drive, Dropbox, OneDrive, iCloud Drive, and Box
- direct Google Drive / Dropbox API mode with saved non-secret defaults
TOOLS -> Cloud Status shows upload/download queues and verify state
TOOLS -> Recover From Cloud runs pull-only cloud recovery without pushing local-only revisions
TOOLS -> Soundtrack Source sets the MIDI URL/path used for playback
soundtrack auto-starts on launch when a source is configured
TOOLS -> Toggle Soundtrack or Alt+M plays/stops the configured MIDI theme source
TOOLS -> Verify Integrity checks the revision chain
bsj backup creates an encrypted snapshot under <vault>/backups/
bsj restore ... --into ... restores a backup to another directory

Lock down

F12 or FILE -> Lock Vault clears unlocked state and returns to the passphrase prompt

Menus and keys

The menu bar is the primary discoverability surface.

Esc opens the menu bar
arrows move between menus and menu items
Enter runs the selected command
function keys remain as direct shortcuts
FILE includes save, quick export, export history, backup policy, backup snapshot, restore, lock, and quit
EDIT includes line tools, stamps, metadata, reveal, and writing-mode toggles
SEARCH includes today/month/all presets, filter clearing, and encrypted cache status
GO includes recents, favorites, random entry jump, calendar, and index timeline
TOOLS includes dashboard, spellcheck, review, sync, soundtrack source + toggle, integrity details, optional AI, and a SYSOP Center menu for operator audits/runbooks
SETUP includes Cloud Provider Setup, saved sync backend defaults, direct cloud target fields, and other runtime settings
TOOLS also includes AI Summary (Optional) and AI Coach Mode (Optional) for guided reflection workflows
HELP includes quick start, first-run coaching, key/menu guides, update checks, doctor output, and About
HELP -> Check for Updates now offers an in-app install action that runs the installer in the background
SETUP includes a live settings summary plus editable vault/sync/device/opening-line/retention/clock/display values
HELP includes About (version/credits), the key sheet, quick-start guide, and searchable guide topics inside the TUI

Primary keys:

F1 help
F2 save revision
F3 date picker
F4 find in entry
F5 global search
F6 replace in entry
F7 index
F8 sync
F9 closing thought
F10 quit
F11 reveal codes
F12 lock
Ctrl+S save fallback
Ctrl+F find fallback
Alt+M toggle soundtrack
Ctrl+Shift+A open AI coach mode (optional)

Keyboard verification:

run cargo test keybinding_ -- --nocapture to exercise function-key and Ctrl fallback routing in tests
on Mac laptops, press fn with F1..F12 unless system settings already treat them as standard function keys

Additional screen-level controls:

soundtrack source defaults to https://www.midi-karaoke.info/21b56501.mid and can be changed in SETUP -> Soundtrack URL/Path
soundtrack source can also be edited directly from TOOLS -> Soundtrack Source
URL sources are cached locally before playback so macOS afplay can play MIDI reliably
search overlay: T today, M month, A all time, C clear filters
date picker: type YYYY-MM-DD, use [ and ] for saved-day jumps, < and > for months with entries
index overlay: type to filter, Shift+S sort, Shift+F favorites only, Shift+C conflicts only
command palette: Ctrl+K
updater logs are written to $TMPDIR/bsj-updater/update.log when started from the TUI

Security model

bsj is local-first, not service-first.

Practical implications:

journal content is not intended to be written to disk in plaintext
vault.json stores metadata and KDF parameters, not entry text
saved revisions, autosave drafts, and backups are encrypted before write
sync targets receive encrypted revision blobs, not plaintext bodies
search indexes are built in memory after unlock and not persisted as plaintext
logs intentionally avoid secrets and journal text

Built-in guides and operator help

Daily use is menu-first inside the TUI. These CLI commands are optional references:

bsj --help
bsj settings
bsj settings --json
bsj doctor
bsj doctor --unlock
bsj guide docs
bsj guide cheatsheet
bsj guide quickstart
bsj guide troubleshooting
bsj guide sync
bsj guide backup
bsj guide macros
bsj guide terminal
bsj guide privacy
bsj guide product
bsj guide datasheet
bsj guide faq
bsj guide support
bsj guide setup
bsj guide settings
bsj guide distribution

Command quick reference

bsj
bsj open 2026-03-16
bsj search "quiet morning" --from 2026-03-01 --to 2026-03-31
bsj search "focus" --whole-word --case-sensitive --limit 20
bsj search "focus" --match-mode any --sort relevance --hits-per-entry 5
bsj search "focus" --range last7 --summary
bsj search "mood:7" --json --context 40
bsj search "ship" --count-only
bsj spellcheck --date 2026-03-16
bsj spellcheck --range last7 --count-only
bsj spellcheck --from 2026-03-01 --to 2026-03-31 --json --limit 50
bsj review --range last30 --goal 750 --json --min-count 2
bsj timeline --query ship --tag work --person Riley --project Phoenix --metadata
bsj timeline --range last30 --group-by week
bsj timeline --save-preset "Recent Work" --query ship --tag work
bsj timeline --preset "Recent Work"
bsj timeline --mood 7 --has-tags --weekday mon,fri --format csv
bsj timeline --from 2026-03-01 --to 2026-03-31 --summary --format json
bsj prompts list --category focus --json
bsj prompts pick --category reflection --json
bsj ai summary --date 2026-03-16
bsj ai summary --range last7 --max-points 5
BSJ_AI_ENABLE_REMOTE=1 BSJ_OPENAI_API_KEY=*** bsj ai summary --date 2026-03-16 --remote
bsj ai coach --date 2026-03-16 --questions 5
bsj export 2026-03-16
bsj export 2026-03-16 --format markdown --output ~/Desktop/entry.md
bsj sync --backend folder --remote ~/Library/Mobile\ Documents/com~apple~CloudDocs/BlueScreenJournal
bsj sync --provider google-drive
bsj sync --provider dropbox
bsj sync --provider onedrive
bsj sync --backend gdrive
bsj sync --backend dropbox
bsj cloud status --backend folder --remote ~/Library/Mobile\ Documents/com~apple~CloudDocs/BlueScreenJournal
bsj cloud status --provider google-drive
bsj cloud status --backend gdrive
bsj cloud status --backend dropbox
bsj cloud recover --backend folder --remote ~/Library/Mobile\ Documents/com~apple~CloudDocs/BlueScreenJournal
bsj cloud recover --provider google-drive
bsj cloud recover --backend gdrive
bsj cloud recover --backend dropbox
bsj backup
bsj backup list
bsj backup prune
bsj backup prune --apply
bsj sysop dashboard
bsj sysop runbook
bsj sysop sync-preview --backend folder --remote ~/Library/Mobile\ Documents/com~apple~CloudDocs/BlueScreenJournal
bsj restore ~/Documents/BlueScreenJournal/backups/backup-20260316T120000Z.bsjbak.enc --into ~/Documents/BlueScreenJournal-Restore
bsj verify

Documentation map

Start here on GitHub:

Support and trust

Need help getting unstuck: SUPPORT.md
Need common answers first: docs/FAQ.md
Need troubleshooting steps: docs/TROUBLESHOOTING.md
Need sync or backup operating guidance: docs/SYNC_GUIDE.md and docs/BACKUP_RESTORE.md
Need to evaluate fit: docs/COMPARE.md
Need security disclosure guidance: SECURITY.md

Packaging and release surface

Build a host-architecture bundle:

./scripts/package-release.sh

Build a universal macOS bundle:

./scripts/package-release.sh --universal

Smoke-test a bundle install:

./scripts/smoke-release-install.sh

Run the full QA gate (same checks enforced in CI):

./scripts/qa-gate.sh
# or
just qa

Non-goals

bsj is intentionally not trying to be:

a collaborative multi-user editor
a mobile journaling app
a rich-text desktop publishing tool
a markdown PKM platform with backlinks and plugins
a hosted cloud account product

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
packaging/homebrew		packaging/homebrew
scripts		scripts
src		src
tests/snapshots/tui		tests/snapshots/tui
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
install.sh		install.sh
justfile		justfile

Navigation Menu

Repository navigation

About

Repository files navigation

bsj

At a glance

New in v2.2.3

Screenshots

Why bsj exists

Product snapshot

Documentation by task

Turnkey install

First five minutes

What using it feels like

Core features and why they matter

Everyday workflow

Write

Move through time

Find things

Optional AI reflection mode (off by default)

Protect and move data

Lock down

Menus and keys

Security model

Built-in guides and operator help

Command quick reference

Documentation map

Support and trust

Packaging and release surface

Non-goals

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

bsj

At a glance

New in v2.2.3

Screenshots

Why bsj exists

Product snapshot

Documentation by task

Turnkey install

First five minutes

What using it feels like

Core features and why they matter

Everyday workflow

Write

Move through time

Find things

Optional AI reflection mode (off by default)

Protect and move data

Lock down

Menus and keys

Security model

Built-in guides and operator help

Command quick reference

Documentation map

Support and trust

Packaging and release surface

Non-goals

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages