# @dclimate/tyche-cli

> `@tyche/cli` is the orderbook CLI for Tyche and WTHRBook.

Latest version **0.2.8** (published 2026-05-05) · 0 weekly downloads

## Install

```sh
npm install @dclimate/tyche-cli
pnpm add @dclimate/tyche-cli
yarn add @dclimate/tyche-cli
bun add @dclimate/tyche-cli
```

Provides the command `tyche`.

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.8 |
| Published | 2026-05-05 |
| First published | 2026-03-10 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 2 |
| Unpacked size | 222.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | davidclimate, 0xswego, phildclimate |

## Links

- npm: https://www.npmjs.com/package/@dclimate/tyche-cli
- npm.io page: https://npm.io/package/@dclimate/tyche-cli

## Dependencies (2)

- [ethers](https://npm.io/package/ethers.md) ^6.16.0
- [commander](https://npm.io/package/commander.md) ^14.0.0

## Recent versions

- 0.2.8 (latest) — 2026-05-05
- 0.2.7 — 2026-05-01
- 0.2.6 — 2026-05-01
- 0.2.4 — 2026-05-01
- 0.2.3 — 2026-05-01
- 0.2.2 — 2026-05-01
- 0.2.1 — 2026-04-24
- 0.1.5 — 2026-03-11
- 0.1.4 — 2026-03-11
- 0.1.3 — 2026-03-11
- 0.1.0 — 2026-03-10

## README

# Tyche CLI

`@tyche/cli` is the orderbook CLI for Tyche and WTHRBook.

It is built around the actual backend API in `../orderbook` and the signing model used in `packages/dapp/services/wthrbook-orderbook.ts`. This package focuses on the flows that exist today:

- health checks
- orderbook, positions, trades, and fee reads
- live SSE event streaming
- shared-address and settlement funding reads/writes
- tradable market discovery and market full-set minting
- signed order creation and submission
- signed cancel creation and submission
- admin fee management
- command and schema introspection for agents

## Runtime configuration

Global flags:

- `--api-url`
- `--chain-id`
- `--environment`
- `--rpc-url`
- `--ponder-url`
- `--settlement-address`
- `--usdc-address`
- `--fee-recipient`
- `--output auto|text|json|ndjson`

Environment variables:

- `TYCHE_API_URL`
- `TYCHE_CHAIN_ID`
- `TYCHE_ENVIRONMENT`
- `TYCHE_RPC_URL` or `BASE_RPC_URL`
- `TYCHE_PONDER_URL`
- `TYCHE_SETTLEMENT_ADDRESS`
- `TYCHE_USDC_ADDRESS`
- `TYCHE_PRIVATE_KEY`

Signing and settlement write commands read the wallet key from `TYCHE_PRIVATE_KEY`. The CLI does not accept private keys on the argv surface.

When contract addresses or the order fee recipient are not passed explicitly, the CLI resolves them from `@tyche/shared/addresses.json` using the selected chain id (`8453` = `base`, `84532` = `baseSepolia`). Settlement funding commands read the actual collateral token from `TycheOrderSettlement.usdc()` so they do not accidentally use the generic chain USDC address when the settlement was deployed against `MockUSDC`.

Ponder defaults are public endpoints, not local services:

- staging and development: `https://ponder-wthrbook-staging.dclimate.net/`
- production: `https://ponder-wthrbook.dclimate.net/`

Override with `--ponder-url` or `TYCHE_PONDER_URL` when testing a custom indexer.

Use `tyche config inspect --output json` to print the resolved non-secret runtime configuration for agents. It includes API, RPC, Ponder, settlement, USDC/collateral, and `WTHRBookFeeRecipient` values, and it does not require `TYCHE_PRIVATE_KEY`.

The CLI also falls back to the frontend env names used by `packages/dapp`:

- `NEXT_PUBLIC_WTHRBOOK_API_URL`
- `NEXT_PUBLIC_PONDER_URL`
- `NEXT_PUBLIC_ENVIRONMENT`

## Command surface

- `health`
- `orderbook list`
- `positions list`
- `trades list`
- `fees quote`
- `fees negotiated list|set|clear`
- `fees discount-tiers list|set|clear`
- `orders create|submit|submit-bulk`
- `cancels create|submit`
- `config inspect`
- `markets tradable|mint-full-set`
- `settlement addresses|balance|approve|deposit|withdraw`
- `stream`
- `describe`
- `schema list|get`

## Output contract

Non-streaming commands emit a stable JSON envelope in `--output json` mode:

```json
{
  "ok": true,
  "command": "orderbook.list",
  "data": {},
  "meta": {
    "timestamp": "2026-04-23T12:00:00.000Z",
    "apiUrl": "http://127.0.0.1:3001"
  }
}
```

Errors use the matching envelope shape on `stderr`:

```json
{
  "ok": false,
  "command": "orders.submit",
  "error": {
    "code": "api_error",
    "message": "invalid signature"
  }
}
```

`stream` emits one JSON object per line in `--output ndjson` mode.

Read commands are bounded by default. `orderbook list`, `positions list`, and `trades list` default to `--limit 100` and accept `--offset`; JSON output includes the backend `pageInfo` metadata (`limit`, `offset`, `nextOffset`, `hasNextPage`).

`orders submit-bulk --output json` keeps the final JSON envelope on `stdout` and writes per-order progress events as JSON lines on `stderr`, so long batches can be monitored without corrupting the machine-readable result. Bulk submission defaults to `--concurrency 2`; orders from the same maker are still serialized to avoid backend submission locks. Add `--summary` to return aggregate counts and bounded failure samples instead of every per-order result. Add `--failed-output-file ./failed-orders.json` to write failed signed payloads as a retryable JSON array.

## Exit codes

- `0`: success
- `1`: unexpected internal error
- `2`: usage or validation error
- `3`: runtime configuration error
- `4`: API request or response error
- `5`: admin auth error
- `6`: signing error
- `7`: chain/RPC transaction error

## Examples

```bash
tyche health --output json
tyche config inspect --chain-id 84532 --output json
tyche orderbook list --pool-id 12 --limit 100 --offset 0 --output json
tyche positions list --maker 0xabc... --output json
tyche trades list --market-id 0xabc... --limit 25 --offset 0 --output json
tyche fees quote --maker 0xabc... --product-type COLLATERAL --output json
tyche orders create --product-type COLLATERAL --pool-id 12 --side BUY --shares 5 --limit-price 0.55 --output json
tyche orders submit --input-file ./order.json --output json
tyche orders submit-bulk --input-file ./orders.json --output json
tyche orders submit-bulk --input-file ./orders.json --summary --failed-output-file ./failed-orders.json --output json
tyche cancels create --order-hash 0xabc... --output json
tyche markets tradable --limit 25 --output json
tyche markets mint-full-set --market-id 0xabc... --amount 10 --approve --allowance-settle-ms 1000 --output json
tyche settlement addresses --chain-id 84532 --output json
tyche settlement balance --owner 0xabc... --output json
tyche settlement deposit --amount 25 --approve --output json
tyche settlement withdraw --amount 10 --output json
tyche stream --market-id 0xabc... --output ndjson
tyche describe orders.create --output json
tyche schema list --output json
```

`orders submit` and `cancels submit` accept either a bare signed payload or the full JSON envelope emitted by the matching `create --output json` command.

Buy orders spend the maker's internal settlement balance, not wallet USDC directly. Deposit USDC into `TycheOrderSettlement` before submitting tradable buy orders; active match locks temporarily reduce the withdrawable amount shown by `settlement balance`.

---
_Source: https://npm.io/package/@dclimate/tyche-cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._