Docs | Kash

The @kashdao/cli package ships the kash binary — a scripting-friendly command-line client over the REST API. Use it for one-off queries, shell scripts, CI jobs, agent integrations, and exploratory debugging.

npm install -g @kashdao/cli
# or: pnpm add -g @kashdao/cli
# or: brew install kashdao/tap/kash       # (Homebrew tap, coming soon)

Verify install:

kash --version
kash --help

Configure

# Interactive setup — walks you through API key, base URL, default chain
kash setup

# Or set explicitly
kash auth set-key kash_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
kash config set baseUrl https://api.kash.bot/v1

# Read it back
kash config show

Config lives at ~/.kash/config.json (written mode 0600). For CI use the env vars instead:

export KASH_API_KEY="kash_live_..."
export KASH_BASE_URL="https://api.kash.bot/v1"

Env vars override on-disk config.

Common commands

# Markets
kash markets list --status ACTIVE --limit 10
kash markets get <market-id>

# Quotes (top-level command; requires the markets:quote scope)
kash quote buy <market-id> --outcome 0 --amount 100
kash quote sell <market-id> --outcome 0 --amount 50

# Trades
kash trade buy <market-id> --outcome 0 --amount 100 --wait
kash trade sell <market-id> --outcome 0 --amount 50
kash trade confirm <trade-id> <token-from-202>
kash trade list --status completed --limit 25
kash trade status <trade-id>
kash trade status <trade-id> --poll     # poll until terminal state

# Portfolio
kash portfolio show
kash portfolio positions --limit 50

# Account telemetry
kash account usage

# Webhooks
kash webhooks list --status failed --limit 20
kash webhooks redeliver <event-id>
kash webhooks rotate-secret
kash webhooks verify --signature "t=…,v1=…" --body-file payload.json --secret $SECRET
kash webhooks replay payload.json --target http://localhost:3000/webhooks/kash --secret $SECRET

# Tracing (top-level command)
kash trace <correlation-id>             # get it from: kash trade status <id> --json | jq -r .correlationId

# Errors
kash explain INSUFFICIENT_SCOPE         # local lookup; works offline
kash explain RATE_LIMIT_EXCEEDED --json

Every command supports --help for full usage.

Output modes

Two output shapes:

Human (default) — colored, tabular, designed for interactive reading.
JSON (--json) — stable envelope, designed for piping into jq, scripts, or agent contexts.

kash account usage --json | jq '.trades["24h"].successRate'
# 0.9166666666666667

The JSON envelope is SemVer-stable. Schema:

{
  "ok": true,
  "data": { ... }
}

On error:

{
  "ok": false,
  "error": {
    "code":         "INSUFFICIENT_SCOPE",
    "message":      "...",
    "recoverable":  false,
    "suggestion":   "Re-issue the key with the trades:write scope.",
    "docsUrl":      "https://docs.kash.bot/developer-docs/api-errors/INSUFFICIENT_SCOPE",
    "requestId":    "req_...",
    "actions":      [
      { "type": "open_url", "url": "https://kash.bot/settings/api-keys", "description": "..." }
    ]
  }
}

actions is the agent-friendly recovery path. Each type is a stable enum (run_command, set_env, wait_and_retry, open_url, check_input) — agents branch on it without parsing prose.

Exit codes

Code	Meaning
`0`	Success.
`1`	Generic error (validation, server, network, etc.).
`2`	Auth failure (missing/invalid key, missing scope).

Rate-limit errors exit 1 (recoverable, but the script should fail loudly). The recoverable boolean and retryAfterMs field tell agents how to handle it.

Quiet mode

Suppress the human-readable preamble when scripting:

kash account usage --json --quiet | jq '...'

Without --quiet, the JSON output is preceded by a one-line summary suitable for terminal output. With --quiet, you get only the JSON envelope.

Tab completion

kash completion bash > /etc/bash_completion.d/kash
kash completion zsh  > /usr/local/share/zsh/site-functions/_kash
kash completion fish > ~/.config/fish/completions/kash.fish

Config import / export

Useful for moving between machines or sharing CI templates:

# Export current config (omits the API key by default — opt in with --include-secrets)
kash config export > ~/kash-config.json

# Import on another machine
kash config import ~/kash-config.json

Retry behaviour

The CLI retries transient failures (network errors, 429, 5xx) with exponential backoff and jitter — same as the SDK. Use the global --max-retries <n> flag (0–10) to override the retry budget for a single invocation — --max-retries 0 disables retries entirely.

Direct (self-orchestrated) mode

Some commands have a direct mode that bypasses the REST API and signs transactions directly with a local key, your own RPC, and your own bundler. Both modes are non-custodial — Kash never holds keys or funds either way; this one just removes the platform-side orchestration so the entire execution stack runs on your infra. See kash protocol --help.

Source & changelog

npm: @kashdao/cli
GitHub (public mirror): KashDAO/cli
Changelog: CHANGELOG.md
Issues / discussions: github.com/KashDAO/cli/issues

TypeScript SDK

The library version of the same primitives, for in-process integration.

Endpoint Reference

The full live spec at /v1/docs.

TypeScript SDK

account

Overview

REST API

Webhooks

TypeScript SDK

CLI

Protocol SDK (TypeScript)

Protocol SDK (Python)

API Error Catalogue

Public Embed API

Embed — Organization Endpoints

Embed — Partner Endpoints

Embed — Thread Endpoints

Embed — Market Endpoints

Embed — Twitter Deep Links

Embed — Guides

Embed — Code Examples

CLI

Configure

Common commands

Output modes

Exit codes

Quiet mode

Tab completion

Config import / export

Retry behaviour

Direct (self-orchestrated) mode

Source & changelog

Next

TypeScript SDK

Endpoint Reference

​Configure

​Common commands

​Output modes

​Exit codes

​Quiet mode

​Tab completion

​Config import / export

​Retry behaviour

​Direct (self-orchestrated) mode

​Source & changelog

​Next

TypeScript SDK

Endpoint Reference

Configure

Common commands

Output modes

Exit codes

Quiet mode

Tab completion

Config import / export

Retry behaviour

Direct (self-orchestrated) mode

Source & changelog

Next