pip install magicicapsula
needs python 3.10+
the mcap command is a shorthand alias for magicicapsula; the two are
interchangeable (mcap seal, mcap open capsule.mcap, ...).
the workflow is staged, so you don't have to add everything at once:
magicicapsula init -u 2030-01-01 # start a draft here
magicicapsula add letter.txt photos/ # stage files/folders
magicicapsula add diary.txt # add more later
magicicapsula status # see what's staged
magicicapsula seal # pack it all into capsule.mcap
the draft lives in a .capsule/ directory (found by walking up from the
current dir). seal reads everything staged and writes the .mcap file.
later, when the date has passed:
magicicapsula open capsule.mcap -d ./out
start a new capsule draft in the current directory.
magicicapsula init [-u DATE] [-n NOTE] [-o OUT]
-u, --unlock DATE unlock date, can also be set at seal
-n, --note NOTE plaintext note shown by info
-o, --out OUT output file name (default: capsule.mcap)
stage files or folders to put in the capsule.
magicicapsula add <paths...>
magicicapsula add --text "dear future me" [--name letter.txt]
echo "..." | magicicapsula add -
--text TEXT stage text directly, no file needed
--name NAME filename for --text or stdin (default: note.txt)
show the draft: unlock date and staged files.
magicicapsula status
unstage files. does not delete them from disk.
magicicapsula rm <paths...>
seal everything staged into a capsule file. flags override the draft's settings and stick.
magicicapsula seal [-u DATE] [-o FILE] [-n NOTE] [-f] [-P]
-u, --unlock DATE unlock date, overrides the draft's
-o, --out FILE output capsule file, overrides the draft's
-n, --note NOTE plaintext note, overrides the draft's
-f, --force overwrite the output if it exists
-P, --no-password seal without a password (anyone can open it after the date)
show a capsule's dates and status. no password needed.
magicicapsula info <file> [--json]
--json print capsule metadata as JSON
open a capsule and extract it, once the unlock date has passed.
magicicapsula open [-d DEST] <file>
-d, --dest DEST directory to extract into (default: current dir)
check a capsule's integrity (and the password, if any) without opening it.
magicicapsula verify <file>
write a calendar (.ics) reminder for a capsule's unlock date. no account
or api needed: import the file into any calendar (google, apple, outlook).
magicicapsula remind <file> [-o FILE] [-b DAYS] [-f]
-o, --out FILE output .ics path (default: <capsule>.ics)
-b, --before DAYS remind this many days before the unlock date
-f, --force overwrite the output if it exists
magicicapsula version
show or edit configuration. settings resolve in the order
default < config file < environment variable. the config file is
~/.config/magicicapsula/config.json; MAGICICAPSULA_PASSWORD overrides it.
magicicapsula config # list all (secrets masked)
magicicapsula config --reveal # list all, secrets shown
magicicapsula config get <key> # show one value and its source
magicicapsula config set <key> <val> # write to the config file
magicicapsula config unset <key> # remove from the config file
absolute YYYY-MM-DD or YYYY-MM-DDTHH:MM (2030-01-01, 2030-01-01T08:00),
or relative from now: +30d, +2w, +6m, +1y.
pip install -e ".[dev]" # installs ruff + pytest
ruff check . && ruff format --check .
pytest # runs the suite with a 90% coverage gate
tests are spec-driven: each core feature (crypto, capsule, draft,
ics, config) is exercised through its public api, and the command layer
is tested by asserting the printed output with the core mocked out. lint and
tests both run in CI on every push and pull request.