Glob
Log in
Menu
Skip to the guide

Reference and help

Output and exit codes

Read JSON results, handle exceptions and use the CLI's exit codes in scripts.

Use --json for scripts that need record IDs, fields or error codes. Human output is formatted for reading, and can change with terminal styling or the command's presentation.

glob notes list --json
glob status --json
glob search "packing" --limit 10 --json

--json belongs to the command being run. It is not a root option to put before a subcommand. A saved output = "json" configuration value does not enable it automatically.

Standard results

Successful standard JSON results go to stdout:

{
  "data": [],
  "schema_version": "1"
}

data can be an object or an array, depending on the command. Keys are sorted, the output is pretty-printed, and date values use ISO-8601. Parse the complete JSON document rather than assuming one result per line.

Standard command failures with --json go to stderr:

{
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Sign in using `glob login`."
  },
  "schema_version": "1"
}

The process exit status carries the numeric outcome. It is not a field inside error. Check both the exit status and the result: sync can print a report on stdout and still exit nonzero.

For example, separate a read result from diagnostics in a shell:

glob notes list --json > notes.json 2> notes-error.json
result=$?
printf 'exit: %s\n' "$result"

A parser error can produce ordinary usage text in notes-error.json, so do not assume every failure file is valid JSON.

Record results

A record summary contains:

Field Type and meaning
id Complete record UUID as a string.
type Record type, such as note or task.
title Display title, falling back to the first body line or (untitled).
is_task Boolean task marker.
done Boolean completion marker.
tags Array of strings.
updated_at ISO-8601 date.

Note lists, task lists, search and record creation return these summaries. glob list and glob pinned put summaries inside their records array.

notes show and notes edit return record details: all the summary fields, plus body, status, source_app, created_at and metadata. Metadata is a string-to-string object.

Not every true/false value is a JSON Boolean. For example, archive/delete, pin/unpin, logout and key-management acknowledgement payloads use some string values such as "true" and "false". Read each command's reference rather than converting every similarly named field to the same type.

Status and version results

glob version --json returns cli_version and protocol_version. The CLI version reported by the current code is 0.6.9; the protocol version is 1.

glob status --json returns:

Field Meaning
cli_version, protocol_version Client and result-format identity.
store_directory Resolved store location.
store_initialized Whether this platform's expected store file exists.
server Effective account service URL, when configured.
authenticated Whether a stored credential can be read.

status checks file and credential presence. It does not open the store to test its contents, and it does not validate the credential with the account service. Use doctor and a read-only account command for those checks.

Optional fields can be absent rather than explicitly null. Handle both when consuming results.

Exceptions to the envelope

Command or condition Actual output
glob patches list --json Raw JSON array without data or schema_version.
Other patches actions Text only; they do not accept --json.
glob relay-node Progress on stderr; --once can print a small result object on stdout. No --json flag.
glob login --web --json Browser-opening instructions on stdout before the result envelope.
Invalid parser options or arguments Usage/error text can be produced before a command's JSON handling runs.
Thrown validation or file errors Some command paths return ordinary error text, including proposal review, browser callback failures and relay setup.
One-time recovery key creation Requires interactive confirmation; recovery keys never appear in JSON success/error results. Existing sync can report recovery_enrollment_required: true; see keys and recovery.

Several validation paths deliberately use ordinary text: a missing TUI, invalid sync-watch timeout, malformed sharing ID, and relay setup are examples. Capture stderr even when you request JSON.

Most standard human-mode failures print ✗ message [CODE] to stdout. JSON protocol failures use stderr. Do not use the location of human text as your only failure test.

Terminal colours are enabled when stdout is interactive. Piped human output is plain. For Ask Glob, the extra model-and-credit line also appears only in an interactive terminal.

Exit codes

Exit Meaning Typical use
0 Success Command completed, including an empty listing.
1 General failure Record not found or an unclassified failure.
2 Invalid usage Malformed UUID, missing input or required confirmation.
3 Authentication required Missing or rejected account session.
4 Authorization denied Permission failure; Ask Glob also uses this for a credits response.
5 Server unavailable Network/service failure, or sync with document failures.
6 Protocol incompatibility Unrecognised response or sync-key failure.
7 Configuration failure Invalid configuration or credential-storage failure.
8 Store unavailable Store could not be opened or used.

These meanings apply to the CLI's structured error paths. Parser validation and uncaught errors can use general parser exits without an error envelope. There is no dedicated exit number for “record not found”: inspect error.code, such as NOT_FOUND.

The per-command result fields for sync, keys, transfer and configuration are documented with those commands. Preserve the spelling shown there: some sync fields use camelCase rather than snake_case.