REFERENCE
JSON and NDJSON output
glnc is built to be a Unix primitive for the blockchain. Every command emits a stable, versioned envelope on stdout when you pass --json. With --watch, that becomes NDJSON, one self-contained envelope per poll, so you can pipe directly into jq, xargs, cron, or any shell script.
Envelope shape
Every JSON or NDJSON line glnc emits has the same outer shape:
glnc balance vitalik.eth --json | jq .On error, ok is false, data is null, and error is { code, message }. New optional fields are additive within a vN; the version bumps only on breaking changes.
stdout vs stderr
When --json or --ndjson is set, stdout is data-only. All progress chatter, spinners, warnings, and the watch-mode alt-screen go to stderr or are suppressed entirely. Pipes stay clean.
glnc balance 0x... --json 2>/dev/null | jq .Schema reference
| Flag | Description |
|---|---|
glnc.balance/v1 | glnc balance ... --json (single document) |
glnc.balance.watch/v1 | glnc balance ... --watch --json (NDJSON stream) |
glnc.tx/v1 | glnc tx ... --json (single document) |
glnc.gas/v1 | glnc gas --json (single document) |
glnc.gas.watch/v1 | glnc gas --watch --json (NDJSON stream) |
glnc.alert/v1 | glnc alert ... --json (NDJSON stream) |
glnc.history/v1 | glnc history ... --json (single document) |
Run glnc schema to print every schema id, or glnc schema balance for a single one. Useful in shell scripts that need to validate the output stream they are consuming.
Source metadata (meta)
balance and gas envelopes carry a meta block so scripted consumers can tell whether a price came from a fresh CoinGecko call or from cache, whether the token list fell back to a hardcoded fallback, and whether any chain RPC failed.
glnc balance 0x... --json | jq .metapartial is the consolidated signal: true if RPC, prices, or the token list degraded in any way for this call. Combine with --strict for scripted short-circuit, or filter with jq 'select(.meta.partial == false)'.
Exit codes
| Flag | Description |
|---|---|
0 | Success. |
1 | User or input error: bad address, unknown command, unsupported --chain. |
2 | All network requests failed. |
3 | Partial result. Only emitted under --strict; default surfaces partial state in meta and exits 0. |
NDJSON in watch mode
Under --watch --json, glnc emits one envelope per poll on its own line. Use jq -c --unbuffered in the pipeline to keep it reactive.
glnc balance 0x... --watch --interval 30 --json | jq -c --unbuffered "select(.event==\"poll\")"Other event lines are {"event":"error", ok:false, error:{code,message}} for failed polls and a final {"event":"stop", reason:"sigint"} on Ctrl+C.
Scripting tips
Always redirect stderr (2>/dev/null or to a log file) when piping stdout into another tool. Progress chatter is intentional but not part of the API. Gate scripted automation on meta.partial and meta.sources.prices.rateLimited before mutating anything: priceUsd: null could mean "CoinGecko doesn't know this token" or "we got rate-limited"; meta is how you tell them apart.
For one-object-per-line on a one-shot command, force NDJSON with --ndjson. Handy when piping through tools that prefer line-delimited input.