BEAMdocs usebeam.sh →

System & data

Health checks, sync, import/export, and integrations. Also home to the two commands with real teeth — sync force and reset — both of which make you confirm before anything happens.

A few low-level support utilities exist beyond these (logs, syslogs, flight, debug) — you'll generally only touch them when the team asks for diagnostics during a support conversation.

Tool-server connections moved to their own page: see MCP & proposals for mcp and proposals.

status

Aliases: none
Purpose: System health overview.
Syntax:

status [backend|ai|usage]

Flags: none
Examples:

status
status ai

See also: ping, sync

Backend reachability, AI provider health, storage, and session details.

ping

Aliases: none
Purpose: Quick backend liveness check.
Syntax:

ping

Flags: none
Examples:

ping

See also: status

sync

Aliases: none
Purpose: Show sync status, or force-resolve a sync conflict.
Syntax:

sync
sync force
sync wipe-remote

Flags: none
Examples:

sync
sync force

See also: snapshots, status, account

BEAM syncs continuously in the background; the status bar shows synced / syncing / pending. sync force overwrites the cloud with this device's state — it first shows a diagnostic receipt (local counts, guard status, any detected corruption) and requires a y to proceed. If the receipt warns about corruption, follow its recommendation rather than forcing.

sync wipe-remote is the other direction and it is the most destructive command
in BEAM. It clears this device first — your workspace, the sync bookkeeping,
every local backup — and only then deletes the cloud copy, so if it stops in
between this device has nothing and the cloud may still have something. It lists
every local storage key it will clear and how much of your workspace lives in
them, then asks you to type a code back rather than press y. Afterwards it
re-reads those keys and reports which are actually gone. The cloud half it can
only say it requested: this device sends the delete and cannot read the server
back to confirm it, and the receipt says so instead of claiming otherwise.

repair

Aliases: none
Purpose: Recover cloud records left encrypted under a previous password.
Syntax:

repair keys
repair status
repair adopt-cloud-key
repair discard-unreadable

Flags: none
Examples:

repair keys
repair status
repair adopt-cloud-key
repair discard-unreadable

See also: sync, snapshots, account

Changing your password re-derives your encryption key. Records already synced to the cloud stay under the old key, and BEAM reports them as records it could not decrypt. repair keys opens a panel where you enter the previous password (or the recovery phrase printed at the time), decrypts those records with it, and re-encrypts them under your current key. The password is typed in that panel and not at this prompt — anything typed here is kept in command history. It always scans and reports first, and writes nothing until you confirm. Records that already open under your current key are never touched, and records that open under no key you have are listed and skipped, never deleted. Do not use sync force for this: it pushes this device's copy over the cloud and cannot recover a record this device cannot read.

repair adopt-cloud-key is for the other shape: your password is accepted on another device but rejected here, or this device shows an empty workspace and reports that it could not open your encrypted data. Your account's key record on the server may differ from the one this device holds. The command reads the server's record and shows you what it would install — the salt, the KDF strength, whether a recovery phrase is on file, when it was last written — and writes nothing until you type repair adopt-cloud-key confirm. Adopting does not open the encrypted data already sealed on this device, and does not delete it; the key record this device held is retained (see repair status) rather than destroyed.

repair discard-unreadable is the clean exit when a record is sealed under a key nothing can recover — you have no old password and no recovery phrase, and no other device can open it either. It scans your cloud records and shows a receipt with the count and the tables involved (never the contents — those never decrypted). Two warnings are stated before you confirm: the discard cannot be undone, so if there is any chance of the old password you should run repair keys first; and if another device can still open this account, recover there first with repair keys, because this command deletes the records for all devices. It deletes nothing until you type repair discard-unreadable confirm, and it deletes only the records that are still unreadable at that moment — a record that has since become readable is left alone. Records that already open under your current key are never touched.

export

Aliases: none
Purpose: Export your workspace data.
Syntax:

export

Flags: none
Examples:

export

See also: account, import

import

Aliases: none
Purpose: Import tasks and docs from files, other tools, or the clipboard.
Syntax:

import
import csv
import todoist
import text
import photo
import file
import clipboard
import history
import undo

Flags: none
Examples:

import csv
import clipboard

See also: export, doc

CSV, Todoist JSON, pasted text, screenshots (text extracted on your device), and files. import history shows past imports; import undo reverts the last one. Dragging files onto the app is the faster path for documents.

drive

Aliases: none
Purpose: Browse Google Drive and link files to tasks.
Syntax:

drive
drive browse
drive search "query"
drive link #N "file"
drive unlink #N <i>
drive status

Flags: none
Examples:

drive search "talk slides"
drive link #5 "Tuesday deck"

See also: mcp, link

Requires a connected Google account; Google integrations are enabled per account during the internal beta.

migration

Aliases: none
Purpose: Show the latest local-storage hygiene audit.
Syntax:

migration audit [--json]

Flags:

--json    raw output

Examples:

migration audit

See also: status

reset

Aliases: wipe
Purpose: Permanently wipe all BEAM data on this device.
Syntax:

reset

Flags:

--all    accepted for compatibility; has no additional effect today

Examples:

reset

See also: account, signout

Corrected 2026-09-10 (A3/#1249): the confirmation is no longer the fixed phrase
reset confirm. A fixed phrase can be typed before you read the warning, or sent
by a script that never saw it, so reset now asks for a code BEAM mints for that
one run — reply y, BEAM shows you the code, you type it back.

reset lists every storage key it will clear and says what those keys hold —
"your 312 tasks, 4 projects and 27 docs on this device", not "47 keys" — before
it asks. Afterwards BEAM re-reads the keys and reports which are actually gone.

--all is accepted and does nothing extra, stated here rather than left to
be discovered: the migration backups (beam_backup_v1_*) it was meant to add
are removed by a plain reset already, and they are listed in the preview
either way. The flag is kept so an old habit does not error.

It clears this device only. Cloud data survives and comes back on sign-in, unless
you also run account delete.