JSON Mode & Scripting

Every Zora CLI command supports --json for machine-readable output. This makes the CLI a powerful building block for shell scripts, CI/CD pipelines, and automated workflows.

JSON Flag

npx @zoralabs/cli <command> --json

When --json is passed:

Output is structured JSON on stdout
The beta warning goes to stderr (won't interfere with parsing)
Interactive UI (live views, spinners) is suppressed in favor of a single JSON result
Errors return a JSON object with error and optional suggestion fields

--json does not skip confirmation prompts on its own — for trade commands (buy, sell, send, claim, pay), pass --yes alongside --json to execute without prompting.

Shell Scripting Examples

Get the market cap of a coin

npx @zoralabs/cli get creator-coin jacob --json | jq -r '.marketCap'
# 434988.18

List trending coin addresses

npx @zoralabs/cli explore --json --sort trending --limit 5 | jq -r '.coins[].address'
# 0x50f88fe97f72...
# 0x834f77c66f90...
# 0xa1dacbd0a9bf...

Check if a coin is up in the last 24h

change is returned as a fraction (e.g. 0.069 means +6.9%), so multiply by 100 for a percentage:

change=$(npx @zoralabs/cli get price-history 0x9b13358e3a02... --json --interval 24h | jq '.change')
if (( $(echo "$change > 0" | bc -l) )); then
  pct=$(echo "$change * 100" | bc -l)
  echo "Coin is up ${pct}%"
fi

Get wallet address

addr=$(npx @zoralabs/cli wallet info --json | jq -r '.address')
echo "Wallet: $addr"
# Wallet: 0xb4a06BdD9e0E60FFE22E4E7590842bfD2069034E

Buy if trending and price is rising

#!/bin/bash
# Find trending coins and buy ones with positive 24h momentum
 
coins=$(npx @zoralabs/cli explore --json --sort trending --limit 5 | jq -r '.coins[].address')
 
for addr in $coins; do
  change=$(npx @zoralabs/cli get price-history "$addr" --json --interval 24h | jq '.change')
 
  # change is a fraction; 0.05 == +5%
  if (( $(echo "$change > 0.05" | bc -l) )); then
    echo "Buying $addr (up $(echo "$change * 100" | bc -l)%)"
    npx @zoralabs/cli buy "$addr" --eth 0.001 --yes --json
  fi
done

Output Modes

Commands with live data (explore, balance, profile) support three mutually exclusive output modes:

Flag	Behavior
`--live`	Interactive, auto-refreshing terminal UI (default)
`--static`	Single snapshot, then exit
`--json`	Structured JSON, then exit

These three flags cannot be combined. --json is the best choice for scripting.

Pagination

Several commands support cursor-based pagination (explore, get trades, get holders, balance coins, profile posts/holdings/trades). Most expose the cursor under pageInfo.endCursor (the exception is get holders, which uses a top-level nextCursor):

# First page
result=$(npx @zoralabs/cli explore --json --sort mcap --limit 10)
echo "$result" | jq '.coins[].name'
 
# Next page — read the cursor from pageInfo.endCursor
cursor=$(echo "$result" | jq -r '.pageInfo.endCursor')
npx @zoralabs/cli explore --json --sort mcap --limit 10 --after "$cursor"

Check .pageInfo.hasNextPage to know when to stop. For get holders, read the cursor from .nextCursor instead.

Error Handling

All errors in --json mode return a consistent format:

{
  "error": "Insufficient ETH balance",
  "suggestion": "Current balance: 0.001 ETH. Need at least 0.01 ETH."
}

Check for the error field to handle failures:

result=$(npx @zoralabs/cli buy 0x... --eth 0.01 --yes --json 2>&1)
error=$(echo "$result" | jq -r '.error // empty')
 
if [ -n "$error" ]; then
  echo "Trade failed: $error"
  exit 1
fi

Environment Variables for Scripting

export ZORA_PRIVATE_KEY=0x...      # Wallet (avoids interactive setup)
export ZORA_API_KEY=your-key       # Higher rate limits
export ZORA_NO_ANALYTICS=1         # Disable telemetry

See Environment Variables for the full list.