CLI

CLI tool for paid semantic search and chunk retrieval on the Zing platform. Executes USDC micro-payments on Sui and queries the Search API.

Prerequisites

1. Rust toolchain — edition 2021
2. USDC on Sui — at least 0.01 USDC on Sui mainnet

Installation

Option 1: Install from GitHub

cargo install --git https://github.com/ZingHall/zing-cli.git zing-cli

Option 2: Clone and build

git clone https://github.com/ZingHall/zing-cli.git
cd zing-cli
cargo install --path . --bin zing

Verify

zing version
# → zing 0.1.0

If you see a version string, installation succeeded. The binary zing is placed in ~/.cargo/bin/.

Configuration

Zing manages its own config and keypair, fully independent from Sui CLI.

First run

On first run, zing auto-creates its config directory:

~/.zing/
  zing_config/
    client.yaml       — active address, active env, RPC endpoints
    zing.keystore     — Ed25519 private key (Sui keystore format)

A new Ed25519 keypair is generated and the address is printed. Fund this address with at least 0.01 USDC on Sui mainnet to use paid search.

Defaults and overrides

Topup Your Wallet

Before running paid commands, make sure your zing wallet has sufficient USDC:

Check your address

zing client active-address
# Active address: 0x013c105e3597ec07e10dad679a276514e1e441ac522ebef32b8109986310dd8e

Check your balance

zing client balance
# Active address: 0x013c105e3597ec07e10dad679a276514e1e441ac522ebef32b8109986310dd8e
# USDC balance: 0.098263 USDC

Fund this address with at least 0.01 USDC on Sui mainnet. Note that 0.01 USDC is the minimum required balance for Sui's gas-free payment mechanism — actual per-request charges are far lower (typically under $0.001).

CLI Commands

zing version

zing version

zing search — Paid semantic search

zing search "what is blockchain"

zing chunks — Paid chunk retrieval

zing chunks "zero-knowledge proofs"

zing expand — Expand truncated chunks

zing expand 94 1603 1802

zing client — Wallet utilities

zing client active-address

zing mcp serve — Start MCP server

zing mcp serve

JSON Output Schemas

The --json flag on search, chunks, and expand commands returns structured JSON instead of human-readable output. All monetary values are in micro-USDC (1 USDC = 1,000,000 micro-USDC).

Search (--json)

{
  "results": [
    {
      "article_id": "0xf6bd...",
      "title": "Gas Fees",
      "excerpt": "When you submit transactions...",
      "heading_path": ["Introduction", "Gas Fees"],
      "score": 0.81,
      "article_token_count": 4200,
      "recency_days": 0,
      "tags": ["cryptocurrency", "defi"]
    }
  ],
  "budget": {
    "paid_usdc": "10000",
    "consumed_usdc": "1250",
    "remaining_usdc": "8750"
  }
}

Chunks (--json)

{
  "chunks": [
    {
      "chunk_id": 94,
      "article_id": "0xf6bd...",
      "title": "What is Web3",
      "text": "Web3 is the next generation of the internet...",
      "score": 2.14,
      "chunk_token_count": 116,
      "heading_path": ["Introduction"],
      "content_type": "prose",
      "language": null,
      "truncated": {
        "content_type": "prose",
        "prose_chars_total": 850,
        "prose_chars_shown": 280
      }
    }
  ],
  "budget": {
    "paid_usdc": "10000",
    "consumed_usdc": "797",
    "remaining_usdc": "9203"
  }
}

Truncation: When truncated is non-null, the text field is an excerpt. The truncated object tells you what was omitted:

Use zing expand <chunk_id> or the zing_expand_chunks MCP tool to retrieve the full text.

Expand (--json)

{
  "chunks": [
    {
      "chunk_id": 94,
      "article_id": "0xf6bd...",
      "heading_path": ["Introduction", "What is Web3"],
      "chunk_text": "Web3 is the next generation of the internet...\n\n(full untruncated text)",
      "content_type": "prose",
      "token_count": 116,
      "truncated": {
        "content_type": "table",
        "table_rows_total": 15,
        "table_rows_shown": 3
      }
    }
  ],
  "budget": {
    "paid_usdc": "10000",
    "consumed_usdc": "2320",
    "remaining_usdc": "7680"
  }
}

Payment Flow

Each request costs a flat search/infrastructure fee (default 0.0005 USDC for ≤20 results, scales linearly for larger limits) plus per-result/per-chunk token fees:

1. Send USDC — the CLI sends USDC via 0x2::balance::send_funds<USDC> to the platform address. USDC coins are always consolidated into address balance before payment to avoid stale RPC cache issues.
2. Sign message — BCS-encodes ApiAccessMessage {q, wiki, transaction_digest, timestamp, expand?, article_ids?} and signs as a PersonalMessage with the Ed25519 keypair from zing.keystore.
3. Submit — sends the signed request to the Search API. The server verifies the on-chain payment, runs the search/chunk pipeline, and returns results up to the paid budget.

The budget breakdown is displayed in the output:

Budget: paid=10000, consumed=1250, remaining=8750

Next Steps

• MCP Server - AI agent integration with MCP tools
• Search API - Explore the search and chunk API endpoints
• Pay-Per-Query API - Learn about per-chunk token-based pricing
• Synthesis - Multi-source collaborative research engine