CLI reference

The 0g command line (@foundryprotocol/0gkit-cli) is the universal, language-agnostic surface for 0G. Every command mirrors a primitive package; --json makes it scriptable from any language.

# Install globally (exposes the `0g` binary):
npm install -g @foundryprotocol/0gkit-cli
0g doctor

# Or run one-off via npx (note the full scope — `npx 0g` resolves to an
# unrelated package on npm):
npx @foundryprotocol/0gkit-cli doctor

Global flags

These apply to every command and are inherited by subcommands.

Precedence: flag > env > preset default. Additional env vars: ZEROG_BROKER_KEY, ZEROG_PROVIDER (for infer).

Output & exit codes

• Human mode: pretty lines; errors print ✗ <message> then → <hint>.
• --json mode: success is { "ok": true, ... }; failure is { "ok": false, "error": { "code", "message", "hint" } }.
• Exit code 0 on success. Exit code 1 when a command throws (any ZeroGError), when 0g doctor has a failing required check, or when 0g attest verify does not verify.

Debugging: --copy-issue-context

Any 0g command accepts --copy-issue-context. When the command throws a ZeroGError, the normal error output still goes to stdout; in addition, a markdown report is written to stderr, suitable for pasting straight into a new GitHub issue.

The report contains:

• Error code, message, hint, and helpUrl.
• The CLI invocation, with --private-key redacted and URL userinfo stripped from --rpc.
• Node.js version, OS, and a timestamp.
• Versions of all installed @foundryprotocol/0gkit-* packages.
• The top 10 frames of the stack.

# Run normally — error to stdout, report to stderr.
0g storage put ./big.bin --copy-issue-context

# Capture only the report:
0g storage put ./big.bin --copy-issue-context 2> issue.md

0g init [name]

Scaffold a runnable, testnet-default project. Defaults the directory name to 0g-app. Writes package.json, .env.example, index.mjs, README.md, .gitignore. Errors (ConfigError) if the target directory exists and is non-empty.

0g init my-app
cd my-app && npm install
0g doctor
npm start

0g doctor

Preflight every 0G surface for the selected network. Checks, in order:

1. rpc (required) — RPC reachable and reports the preset's chain id.
2. signer (soft) — key present and the address is funded (read-only is valid; absence is not a failure).
3. storage-indexer (soft) — indexer endpoint reachable (HTTP < 500).
4. da-encoder (soft) — DA encoder reachable (falls back to local mode).
5. faucet (informational) — faucet guidance for the network.

Exit 1 only if a required check fails (i.e. RPC).

0g doctor --network galileo
0g doctor --json | jq '.checks[] | select(.ok==false)'

0g doctor --fix

Pass --fix to apply the safe auto-fixes doctor can make without touching the network or installing anything (advisory-only by design — Decision D85):

• Regenerates a missing .env / .env.example from your define0GConfig.
• Prints the exact command to bump a stale package pin (it never edits your package.json for you).

0g doctor --fix
# ✓ wrote .env.example from 0g.config.ts
# → stale pin: run `npm i @foundryprotocol/0gkit-cli@latest`

--fix never installs dependencies, never sends a transaction, and never mutates network state — it only writes local .env* files and prints next steps.

0g dev

Spin up a local 0G stack (chain + storage + compute + DA) for offline development — no testnet funds, no RPC latency.

Common start flags: --port-chain <n> (default 8545), --port-da <n> (default 5680), --mnemonic <phrase>, --state-dir <path> (default ~/.0g-dev), --detach (exit once services are up — for tests/CI).

0g dev --detach                       # start in the background
0g test --local                       # run conformance against it (see below)
0g dev status
0g dev reset                          # tear down + wipe state

0g test

Run the offline conformance suites — storage / DA / and other primitive round-trips — to prove your install and config work before you ship. Lazy-loads @foundryprotocol/0gkit-testing so it never bloats cold-start (Decision D39).

0g test                       # all suites, galileo
0g test --suite=storage,da    # just these two
0g test --local --kits        # local stack + every applied kit's check
0g test --json | jq '.ok'

Exit 1 if any suite fails — wire it as a CI gate before deploy.

0g chain

Native-chain helpers.

0g chain balance 0xYourAddress --network aristotle
0g chain tx 0xYourTxHash --json
0g chain faucet 0xNew --network galileo   # → https://faucet.0g.ai

0g storage

0G Storage. Networks restricted to aristotle | galileo (a ConfigError otherwise).

export ZEROG_PRIVATE_KEY=0x...   # funds the upload tx
ROOT=$(0g storage put model.bin --network galileo --json | jq -r .root)
0g storage get "$ROOT" ./out.bin
0g storage exists "$ROOT" --json

0g infer

Run a chat completion against a 0G compute provider. Requires a broker key (ZEROG_BROKER_KEY, falling back to ZEROG_PRIVATE_KEY / --private-key) and a provider (--provider or ZEROG_PROVIDER).

export ZEROG_BROKER_KEY=0x... ZEROG_PROVIDER=0xPROVIDER
0g infer -m "Summarize 0G in one line" --network galileo
echo "What is 0G DA?" | 0g infer --json | jq -r .output

0g da

0G Data Availability.

0g da publish payload.json --network galileo --json | jq -r .digest
echo '{"a":1}' | 0g da publish - --json
0g da verify payload.json 0xDIGEST   # prints MATCH / MISMATCH

0g attest

TEE attestation. Operates on a SignedEnvelope JSON file ({ envelope, digest, signature }).

0g attest verify signed.json --signer 0xCoordinator
0g attest report signed.json --json

0g contracts

Generate a typed TypeScript client from a contract ABI — either an off-chain Foundry artifact or a verified ABI fetched from the chain explorer.

import fetches the ABI from 0G ChainScan's Etherscan-compatible /open/api (keyless; set OG_EXPLORER_API_KEY only for rate-limit relief). --name is required when importing by address — the explorer's getabi carries no contract name. An unverified contract, an HTTP error, or a malformed payload throws a ConfigError pointing you at --abi <path>.json — it never fabricates an ABI.

# From a verified on-chain contract (galileo default):
0g contracts import 0xAbc…DEF --name MyToken
# → wrote ./0gkit/contracts/MyToken.ts

# From a local Foundry artifact:
0g contracts generate --abi ./out/MyToken.sol/MyToken.json --out ./src/contracts

0g contracts list --json

The generated client is fully typed and wraps @foundryprotocol/0gkit-contracts — see the contracts package docs.

0g cost

Cost forecasting across 0G primitives. Two modes — synthesise estimates from flags, or aggregate real per-op costs from a Jaeger trace emitted by @foundryprotocol/0gkit-observability.

# Hypothetical: forecast a workload before you run it
0g cost forecast \
  --storage 1024,4096 \
  --compute "summarise|llama-3-8b|512" \
  --da 2048 \
  --json

# Real: replay an existing trace through the cost calculator
0g cost forecast --from-jaeger ./trace.json --json

--from-jaeger scans every span carrying the 0gkit.op attribute (emitted automatically by @foundryprotocol/0gkit-observability), groups by op, and sums 0gkit.fee_native + 0gkit.gas_native. Dry-run spans (0gkit.dry_run=true) and errored spans (any 0gkit.error_code tag) are counted but excluded from totals — they did not spend on-chain resources.

The JSON envelope from --from-jaeger:

{
  "ok": true,
  "source": "jaeger",
  "file": "trace.json",
  "spansScanned": 42,
  "spansAttributed": 18,
  "spansSkipped": 2,
  "byOp": {
    "storage.upload": {
      "count": 3,
      "totalGas": "240000",
      "totalFeeWei": "3000000000",
      "totalSizeBytes": 12288
    },
    "compute.inference": {
      "count": 12,
      "totalGas": "0",
      "totalFeeWei": "6000000000",
      "totalInputTokens": 2400,
      "totalOutputTokens": 6144
    },
    "da.publish": {
      "count": 3,
      "totalGas": "0",
      "totalFeeWei": "1536000000",
      "totalSizeBytes": 1536
    }
  },
  "totalGas": "240000",
  "totalFeeWei": "10536000000"
}

Download a trace dump from the Jaeger UI (Trace → ⋮ → Download JSON) or hit the query API directly (/api/traces/<id>). The same parser works against any OTLP collector that exports the Jaeger JSON format.

Pass - as the file path to read a Jaeger envelope from stdin — pipes cleanly from 0g traces inspect <id> --json (see below).

0g estimate

Quick per-op cost estimates for a concrete input (a real file, a prompt, a byte size). Where 0g cost forecast sums hypothetical or trace-aggregated workloads, estimate answers "what will this one op cost?"

0g estimate storage ./model.bin --json
0g estimate compute -p "Summarize 0G" --model llama-3.1-8b --max-output 256
0g estimate da --bytes 4096

0g traces

Inspect local 0gkit trace JSONL files written by the OGKIT_TRACE_DIR opt-in mirror in @foundryprotocol/0gkit-observability. Off by default; when the env var is set, every instrumented span is written to <dir>/<YYYY-MM-DD>-<traceId>.jsonl in addition to your configured OTel exporter. Pure local sink — no network, no extra infra.

Quickstart

# In the process that runs your 0gkit code:
export OGKIT_TRACE_DIR=.0gkit/traces

# After requests have run:
0g traces list --last 5
0g traces inspect <traceId>

# Replay one local trace as a cost forecast:
0g traces inspect <traceId> --json | 0g cost forecast --from-jaeger -

Both subcommands accept --dir <path> to override OGKIT_TRACE_DIR for a one-off look at a directory copied from a teammate. --json is supported on both for piping into other tooling.

0g kits

Compose your app from kits — overlays that drop in a portable lib/, per-base adapters/, and (for React bases) a ui/ tier, deduping dependencies as they apply. See the kits guide and authoring guide.

0g add flags: --base <name> (force the base: react-app | mcp-agent | node | …), --pm <pnpm|npm|yarn> (which package manager appears in the printed install hint), --dry-run (preview what would be written, touch nothing). Kits are fetched from the template registry via giget at apply-time.

0g kits list --base react-app
0g kits info agent-memory
0g add agent-memory live-feed        # applies both (composed deps resolved first)
0g add ai-oracle --dry-run           # preview only

0g jobs

Inspect @foundryprotocol/0gkit-jobs queues.

Flags: --backend <memory|sqlite> (default sqlite), --path <path> (sqlite file, default ./.jobs.db).

0g jobs status job_abc123 --backend sqlite --path ./.jobs.db --json

0g mcp init <agent>

Wire the 0gkit tool set into your AI editor. Writes the MCP server config for the given agent — one of cursor, claude, windsurf, codex. In a kitted mcp-agent project it also surfaces your applied kits' tools.

0g mcp init cursor            # writes project-level MCP config
0g mcp init claude --global   # user-level config
# → restart the agent to pick up the 0gkit tools

Writes editor config only — it never mutates network state. See the MCP guide.

0g foundry … (opt-in, hidden)

The optional Foundry plugin namespace. Hidden unless @foundryprotocol/mcp is installed or you pass --foundry. Absent by default — the neutrality boundary stays green by construction.

Scripting from any language

--json is stable and meaningful exit codes make 0g a clean subprocess:

# Python
import json, subprocess
r = subprocess.run(["0g","storage","exists",root,"--json"],
                    capture_output=True, text=True)
print(json.loads(r.stdout)["exists"])

Related

storage · compute · da · attestation · MCP guide (the same surface for agents).