Glob
Log in
Menu
Skip to the guide

Reference and help

Troubleshooting the CLI

Diagnose installation, store, sign-in, sync and scripting failures using the CLI's actual messages.

Start by checking the command you ran, which binary your shell selected, and which store it uses. A working local note command and a failed hosted command can have different causes.

command -v glob
glob version
glob --help
glob status --json
glob config show

status reports local credential presence and the store's expected file. It does not validate the session or open the store. glob doctor opens or creates the selected store and reports its contents. On Linux, glob sync status --json reports local sync state without contacting the account service.

When asking for help, include the exact command with secret values removed, OS and architecture, static or dynamic Linux variant, version output, exit status and error code. Keep passwords, account sessions, API keys, sync passphrases and recovery keys out of pasted output.

The command does not start

Symptom or message What to check
glob: command not found The default install directory is ~/.local/bin. Add it to PATH and reopen the shell.
glob-tui is not installed Rerun the bundled installer. Bare glob needs the separate TUI launcher.
could not launch glob-tui at … Check the launcher's executable permission and reinstall it.
glob binary not found at … The TUI needs the native CLI at ~/.local/bin/glob or the path named by GLOB_BIN; it does not search PATH at runtime.
Installer rejects the operating system or architecture Use a supported macOS or 64-bit Linux download. There is no 32-bit substitute.
A command is missing from help Check platform availability. In particular, macOS does not have sync, share, patches or relay-node.

The TUI needs Python 3 with curses and an interactive terminal. A terminal setup error is separate from the CLI store. See TUI help for its exact input and terminal limits.

Local records work, hosted commands fail

On Linux, check which build you installed. The installer defaults to a fully static build whose HTTPS support fails. On x86_64, reinstall the dynamic variant:

curl -fsSL https://install.colli.dev | GLOB_INSTALL_DYNAMIC=1 sh

Linux arm64 has only a static release in this distribution. Repeated sign-in attempts will not fix its HTTPS limitation.

Otherwise, check the effective service:

glob server show
glob config show

GLOB_SERVER_URL overrides a saved URL. Setting a new URL in the configuration does not remove that environment override. Use https://api.colli.dev for the hosted account service.

SERVER_NOT_CONFIGURED means no usable server was resolved. URL validation can also report Unsupported scheme. Use HTTPS for a remote service. The HTTP exception is limited to services on this computer.

SERVER_UNAVAILABLE means a request could not reach the service. SERVER_ERROR means the service returned an unsuccessful status. Keep the accompanying message when reporting either.

Sign-in and permissions

AUTHENTICATION_REQUIRED can mean no session was stored or the server rejected it. status showing authenticated: true only confirms a credential was read. Run a read-only account request such as glob keys list to check it with the service, then sign in again if needed.

Password sign-in can report AUTH_LOGIN_<status>, browser exchange AUTH_EXCHANGE_<status>, and username setup PUBLIC_USERNAME_<status>. Read the accompanying message. A 401 login/exchange response exits 3; other status responses can exit 5.

Message Action
provide a token via --stdin or --token Choose the token input method, or use --email or --web.
--password-stdin requires --email Supply the account email too.
--web cannot be combined with token or password login options Run one login method at a time.
public username ending in -AI is reserved for agents Use a nonempty human username without that ending.
timed out waiting for browser sign-in (5 minutes) Start a new browser sign-in and finish it on the same computer.
KEYCHAIN_ERROR Check the current user's Keychain on macOS or credential-file location and permissions on Linux.
AI_ERROR_401 Renew the account session.
AI_ERROR_402 Read the service message and check account credits.
BAD_RESPONSE Update the CLI; report the message if the current download still cannot read the reply.

glob logout removes the local session. It is not a store reset and does not repair a wrong sync passphrase.

Empty lists or unexpected data

glob status --json
glob doctor --json
glob notes list --include-tasks --json
glob tasks list --all --json

Check the resolved store directory first. --store overrides GLOB_STORE_DIR, which overrides the default. The Mac application's store is separate from the CLI's store. Account sign-in does not itself download records.

notes list excludes tasks unless you add --include-tasks; both note and task listings exclude archived records. tasks list hides completed tasks unless you add --all. Large stores can exceed the commands' fetch windows. Use notes show <full-id> to check a known record directly.

glob list follows the selected container; glob notes list is a general active-record listing. On Linux, glob switch --root returns the node view to the root.

Search on Linux uses word prefixes; macOS searches substrings. For example, a fragment found inside a word on macOS need not match on Linux. See search details.

Store errors

Error or message Action
CONFIGURATION_FAILURE: Cannot create store directory … Select a writable directory or fix its parent permissions.
STORE_UNAVAILABLE: Failed to open the Glob store: … Keep the underlying message. Check the selected directory and whether another process is holding a long write.
SQLITE_BUSY or a persistent lock error Stop conflicting writers before investigating. Do not remove database journal files as a repair attempt.
This command requires a package-backed Glob store. Node-view commands need the Linux store. Their presence in macOS help does not provide a supported store there.
export requires a package-backed Glob store (Linux CLI). Portable export requires the Linux store.
projection rebuild is only available for package-backed stores The rebuild option requires Linux.

On Linux, glob doctor --rebuild-projection --json rebuilds the record listing from available documents. It does not fetch documents missing from the device. A quarantined document can remain absent from listings after a rebuild; inspect the reason in glob sync status --json.

Invalid IDs and confirmations

INVALID_ARGUMENT with is not a valid UUID usually means a shortened display ID was supplied. Use the complete id from a JSON listing.

NOT_FOUND means that ID is not available in the selected store. For links, source or target record not found means at least one end is missing. Confirm the store and inspect both records before creating the link again.

CONFIRMATION_REQUIRED means the command needs explicit consent. Record deletion, key revocation and account-wide key freezing require --yes. Check the target before adding it. Sync reset has its own interactive confirmation. Proposal apply asks you to review with glob patches show <id> before rerunning with --yes.

A proposal that reports proposal is already applied or proposal is already rejected cannot be resolved again.

Sync, recovery and relay

  • INVALID_ARGUMENT asking for a passphrase: supply --passphrase-stdin, or the configured environment value. A nonempty GLOB_SYNC_PASSPHRASE takes precedence over stdin.
  • SYNC_KEY_FAILED: use the current sync passphrase for the account. Signing in again does not change that passphrase.
  • RECOVERY_ENROLLMENT_REQUIRED (exit 2): complete first encryption setup with interactive glob sync now --passphrase-stdin, save the key and type SAVED, then return to the script, TUI or service. The refused command creates no account keys.
  • RECOVERY_ENROLLMENT_CHANGED (exit 2): another device completed setup first. Discard the key just shown here, unlock again and use the key saved on that device.
  • RECOVERY_ENROLLMENT_CANCELLED (exit 2): enrollment was cancelled before account keys changed.
  • RECOVERY_KEY_UNSUPPORTED: the connected service refused adding a recovery key. See recovery setup before retrying.
  • Sync exits 5 with document_failures: read each document's reason. Other documents may have synced successfully.
  • Sync status lists quarantined: the stored document cannot be converted into a valid visible record. Keep the reported ID and reason for support.
  • Relay reports no usable key or scope: follow relay setup. Rotating an API key also requires updating the clients and relay using it.

Read sync and sharing for watch behaviour, reset and partial results. Avoid blindly repeating a write that failed after starting: check whether the intended record or key already exists.

Other structured errors

Some errors include a status number or details supplied by the connected service. Keep that message when asking for help; the code identifies which part of the request failed.

Code Meaning and next step
ENCODE_FAILED The command could not prepare its request. Check supplied scope JSON where applicable; if valid input still fails, update the CLI and contact support. Exit 1.
SYNC_FAILED A sync operation failed outside the more specific categories. Read its attached reason; a network error during key setup can also appear here. Exit 1.
KEY_SCHEME_HTTP_<status> The service refused an identity or document-key request. 404 uses exit 2; other non-authentication statuses use exit 5. Check the selected account, document and message.
RELAY_HTTP_<status> A relay request failed. 401 uses exit 3; other statuses use exit 5. Renew the session for 401, otherwise read the service message and connection state.
IDENTITY_KEY_MISSING A required active identity or older identity generation could not be found. Check that the other member has set up sync; if it persists, contact support. Exit 6.
IDENTITY_KEY_INVALID Returned identity-key data could not be used. Update the CLI and report the message if it persists. Exit 6.
DOCUMENT_KEY_INVALID Returned document-key data could not be used. Preserve the document ID and error for support. Exit 6.
UNSUPPORTED_RECORD_TYPE The selected node's record type cannot be used for this operation. Check the selected record. Exit 2.
ALREADY_EXISTS A node operation tried to create an ID that already exists. Inspect the resulting view before repeating it. Exit 2.
UNAVAILABLE The selected store or platform cannot perform this operation. Check availability. Exit 2.

Markdown and JSON surprises

INVALID_EXPORT names an unsupported version or unreadable field. Portable v1 files and old flat or Node/Note/Task directories are accepted. Existing records are kept; see transfer.

If a script cannot parse the result, check output exceptions. patches list returns a raw array, browser sign-in prints instructions before JSON, and parser errors can be plain text. Always inspect the process exit status and capture stderr.

For help, contact [email protected]. Account and deletion questions go to [email protected].