Sync and shared document keys

Sync sends this CLI store's changes and brings in changes from your account's other devices. Use glob sync now for one pass, or leave glob sync watch running while you work.

These commands, including glob share grant, are available in the Linux CLI. The macOS CLI does not register them. HTTPS access requires a Linux build that supports it; see installing the CLI.

Before you sync#

Set your server and sign in using the CLI account commands. Sync also needs your sync passphrase. It is separate from your account password and your Data API keys.

Supply the passphrase in either of these ways:

• Set GLOB_SYNC_PASSPHRASE in the environment.
• Add --passphrase-stdin and supply one non-empty line on standard input.

The environment value takes priority. If it is non-empty, the command uses it even when you also specify --passphrase-stdin; it does not read the input line. There is no interactive passphrase prompt in these commands.

For example, in Bash you can read the passphrase without displaying it, then sync:

read -rs GLOB_SYNC_PASSPHRASE
export GLOB_SYNC_PASSPHRASE
glob sync now

Type the passphrase after the first line and press Enter. Use your existing sync passphrase if you have already set up encryption for this account. First encryption setup requires an interactive terminal: save the recovery key shown there and type SAVED before the envelope is published. JSON, the TUI, watchers and relay services cannot bootstrap encryption. Cancelling changes no account keys. See recovery keys.

Every sync subcommand accepts --store <directory> and --json. The store defaults to GLOB_STORE_DIR, then ~/.glob/store. Use the same store selection for your editing commands and your sync commands.

Sync once#

glob sync now
glob sync now --passphrase-stdin
glob sync now --store ~/glob-work --json

glob sync also runs now when you omit the subcommand. It reads changes from your account, downloads documents this store has not held before, reconciles the documents already here, and uploads pending edits. It also syncs your account's pins, lists, and projects. Downloaded changes become available to the CLI's reading commands.

Human output reports sync complete or sync finished with errors, followed by pushed, pulled, and any document sync failed lines. Read every failure even when other documents synced successfully.

With --json, the success envelope's data contains:

A pass with document failures prints its report and exits with code 5. A JSON envelope on stdout therefore does not, by itself, mean every document synced. Check the exit code and document_failures.

The change position advances past individual document failures so other documents can continue. A document already held here is considered again on a later full sync. If a document has never downloaded successfully, fix the reported problem and use reset before another sync to revisit the earlier change list.

Keep syncing#

glob sync watch
glob sync watch --wait-timeout 20
glob sync watch --wait-timeout 5 --max-windows 3

The watcher syncs once at startup, then waits for remote changes. At the end of each wait it checks for local edits too. An edit made by another CLI process can therefore wait until the current window closes before uploading.

Progress lines begin sync watch: and go to stderr, including in JSON mode. They describe startup sync, remote or local changes, document failures, retries, and the final number of wait windows.

Press Ctrl+C to stop. The watcher finishes its current work before leaving, so it may not stop immediately. Temporary failures while waiting are retried with increasing delays. Rejected credentials stop the watcher; sign in again before restarting it. A failure during a sync pass can also stop it.

The watcher refuses first encryption setup with RECOVERY_ENROLLMENT_REQUIRED. Complete interactive glob sync now once first. Existing accounts without recovery remain usable and receive a reminder to enroll later with glob keys recovery.

Inspect this store#

glob sync status
glob sync status --json

Status reads the selected store without contacting the server or asking for a passphrase. Its authenticated value means that a credential is stored; it does not verify that the server still accepts it.

Human output labels these cursor, pending outbox, authenticated, quarantined records, and last failures. An outbox is the queue of edits waiting to upload. A failure entry includes the number of attempts and the last attempt time, where recorded. These are pending attempted uploads, rather than a complete history of every sync error.

Re-read the change list#

glob sync reset
glob sync reset --yes
glob sync reset --yes --json

Reset sets this store's change position to zero. It keeps the documents here. The next glob sync now re-reads the account's change list from the beginning.

Without --yes, the command asks for confirmation. Enter y or yes to continue; anything else exits with code 2. For scripts and JSON use, pass --yes, because --json alone does not suppress the confirmation prompt.

The JSON result is { "previousCursor": <old position>, "cursor": 0 } inside data. Reset needs neither a passphrase nor a server connection.

Grant keys to pending members#

glob share grant <document-uuid> --passphrase-stdin
glob share grant <document-uuid> --json

Use share grant when an existing shared document has members waiting for its document key. The argument must be the document UUID. The command opens your own document key and grants it to the pending members returned for that document. It needs your configured server, signed-in session, sync passphrase, and selected store.

Options are --passphrase-stdin, --store <directory>, and --json. There is no recipient argument: this command handles pending members, rather than creating invitations or choosing members.

Human output says document key grant complete and shows document and granted. JSON data contains document_id and granted; no recovery key is returned in JSON. A count of zero means that the command granted no pending member keys.

When something fails#

For account access and recovery beyond these commands, see the account sync guide.