Epsitec.Briefcases.Cli 2.8.1.2629

Briefcases CLI

A command-line tool for managing encrypted briefcases — zero-knowledge, event-sourced document storage with post-quantum cryptography.

Installation

dotnet tool install -g Epsitec.Briefcases.Cli

Quick Start

# Provision your identity keys against auth (uid is assigned, not chosen;
# prompts for --login / --auth-pwd / --totp when omitted). This also logs
# you in: the session is stored and refreshed automatically from then on.
briefcases identity provision

# Create a new briefcase
briefcases create

# Add files
briefcases add ./document.pdf
briefcases add ./project-folder

# Restore files from briefcase
briefcases restore

# View briefcase tree
briefcases tree

# Show a QR code to import your keys into the mobile app
briefcases export-keys

Commands

Successor continuity

The owner of a briefcase never changes, but the owner may designate successors who can obtain full read access if the owner disappears. A designated successor has no privilege until it succeeds.

The probation window defaults to 48 hours: a successor cannot finalize a claim until it elapses, giving the owner time to veto. Override it at creation with briefcases create --probation <minutes> (e.g. 0 to disable, for tests).

Owner commands:

Successor commands:

After acceptance, sync then ls/read/tree return every node to the successor. The successor never becomes the owner and cannot act as the owner.

Social recovery

An owner who loses their private keys and their recovery phrase can regain access through a trusted member. The briefcase's recovery vault holds Access-Key shards the owner deposited ahead of time: one entry per chosen member, each an independent 2-of-2 split — one shard sealed to that member, the other kept by the server. Neither shard alone reveals anything.

Provisioning a member is a trust decision: an assisting member receives their whole entry, so choose recovery peers as deliberately as you would a successor. Owner commands, run while access is still held:

The recovery itself, for an owner A assisted by a member B:

# A — start over with a fresh identity (new keys, new phrase):
briefcases identity provision --reprovision

# A — open the recovery request for the briefcase:
briefcases recovery request --bid <bid>

# B — assist: prepares the rekey package, prints a PIN for A:
briefcases recovery assist <bid>

# A — accept the recovery invitation with B's PIN, then complete:
briefcases invite accept <invite-id> <PIN>
briefcases recovery complete --bid <bid>

recovery complete reconstructs the Access Key from the shards, verifies it against the genesis recovery anchor, restores access, and re-wraps the owner's custom LAKs. It is idempotent — re-run it after an interruption and it finishes only the missing steps. There is no probation here: the safeguard is B, who should verify out of band that A really lost their keys before assisting.

Time capsules

timelock seals arbitrary bytes so they cannot be decrypted before a chosen time — no briefcase, no server account required. It seals to a public randomness beacon (drand's quicknet network): the file stays unopenable, by anyone, until the beacon for its round is published, and no earlier. The produced file is a standard tlock/age capsule — it opens with the official tlock CLI or tlock-js, and vice versa.

Exactly one of --at <timestamp>, --minutes <n>, or --round <n> chooses the unlock point; --in/--out default to stdin/stdout, so the command composes with pipes. --out omitted means the sealed or recovered bytes are the command's output — no other text is printed, so a pipeline never sees anything but the payload.

# Seal a short secret for one hour, to a file.
echo "the launch code is 4-8-15-16-23-42" | briefcases timelock seal --minutes 60 --out capsule.age

# Check when it opens, without any key material or network access.
briefcases timelock inspect --in capsule.age
#   Round: 12345678
#   Chain hash: 52db9ba7...
#   Unlock time: 2026-07-08T15:30:00Z (locked)

# Try to open it early: reports the unlock time and exits cleanly, no error.
briefcases timelock open --in capsule.age
#   Still timelocked; unlocks at 2026-07-08T15:30:00Z. Run 'briefcases timelock open' again after that time.

# ... after the hour has passed ...
briefcases timelock open --in capsule.age
#   Opened.

open fetches the unlocking beacon from the public relays and verifies it before decrypting; a relay outage is reported as a retryable warning, never a hard failure. A tampered or corrupted file is rejected with a clear error.

Workspace cards

A workspace card carries small, human-meaningful metadata for a briefcase — workspace name, owner, an optional description, colour, icon, and tags — that members read without downloading the ledger and that the server never sees in cleartext.

The card is stored in an internal system:-tagged anchor node, hidden from the file views by default. Reveal it with tree --system (add --show-gen for its generation) or materialize it with restore --system.

Cold-read verification. When you hold an access token, list and card show verify the card's owner signature against the auth directory named by the token's iss claim (defense in depth). list marks a verified entry green with a trailing ✓ and a tampered one red with ✗; card show adds a Verified: line (yes / NO — signature invalid / not checked). Verification is best-effort: with no token, or when the signer key cannot be resolved, the card simply shows as not checked and the listing still succeeds.

Sessions and tokens

Log in once, work all day — the CLI manages its own access tokens:

• briefcases identity provision (first run) or auth-cli login establishes the session and stores it in the .auth-cli/ directory next to the storage root, shared with the external auth-cli tool.
• Every online command then mints fresh access tokens automatically from the stored refresh token — at startup and mid-command, so long transfers and listen survive token expiry — and persists the refreshed pair back for the next invocation.
• When the session eventually dies (refresh token expired or revoked), the command exits with a single actionable error telling you to run auth-cli login (or briefcases identity provision on a fresh machine).

No manual token refresh is ever needed in the nominal flow. Run any command with --verbose to trace the token lifecycle (source, remaining lifetime, refresh and write-back decisions); identity status prints a Session: line describing the stored session without touching the network.

Global Options

• --root <path> — Override briefcase storage root (default: ./.briefcases/)
• --settings <name> — Override settings filename (default: default.json)
• --bid <id> — Override briefcase ID (* is only useful for generation paths such as create)
• --url <url> — Override server URL for this invocation
• --auth-url <url> — Override the auth service URL for this invocation (persist it with configure auth-url=…; default: the production auth)
• --storage <backend> — Storage backend: fs / filesystem (default) or zip
• --dir <path> — Override working directory
• --token <jwt> — Use this exact access token for the invocation: it is never refreshed and never persisted; scripting callers own its lifecycle
• --ignore-auth-cli — Do not touch the local .auth-cli/ session at all: no token is read from it and nothing is written back (not even by identity provision)
• --resource <urn> — Bind minted access tokens to the given resource audience (RFC 8707); persist it with configure resource=… (default: unbound)
• --verbose — Enable verbose output (includes the token lifecycle diagnostics)
• --insecure — Disable TLS certificate validation

License

MIT — Copyright © 2026, EPSITEC SA, CH-1400 Yverdon-les-Bains, Switzerland