CLI

The KeyStone CLI helps platform developers during development and debugging. The standout feature is keystone listen which forwards webhooks to your local server without ngrok or tunneling tools.

Installation

npm install -g @keystoneos/cli

Or use without installing:

npx @keystoneos/cli login

Source on GitHub

Authenticate with your M2M credentials. Stored locally in ~/.keystone/config.json.

keystone login

You’ll be prompted for your client ID and secret. Or pass them as flags:

keystone login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

Set the environment (default: production):

keystone login --environment staging

Webhook Forwarding

Forward webhook events to your local development server. No ngrok needed.

keystone listen --forward-to http://localhost:3000/webhooks/keystone

This:

Creates a temporary webhook endpoint on KeyStone
Polls for new events
Forwards each event to your local server via HTTP POST
Shows events in your terminal with colored output
Cleans up the temporary endpoint on exit (Ctrl+C)

Example output:

✓ Listening for webhooks...
  Forwarding to: http://localhost:3000/webhooks/keystone

12:04:15  test.ping                            -              → 200 OK (42ms)
12:04:18  settlement.state.awaiting_deposits   550e8400-e29b  → 200 OK (38ms)
12:05:02  settlement.state.finalized           550e8400-e29b  → 200 OK (51ms)

Settlements

List settlements

keystone settlements list
keystone settlements list --state FINALIZED
keystone settlements list --limit 10

Example output:

ID            State              Reference        Parties              Created
a1b2c3d4...   AWAITING_DEPOSITS  TRADE-2026-0042  Securitize, Ondo    5m ago
b2c3d4e5...   COMPLIANCE_CHECK   TRADE-2026-0041  BlackRock, Fidelity 10m ago
c3d4e5f6...   FINALIZED          TRADE-2026-0040  Centrifuge, Maple   2h ago

Total: 3 settlements

Get settlement detail

keystone settlements get a1b2c3d4-e5f6-7890-abcd-ef1234567890

Shows state, parties, legs, event timeline, and timeout.

Instructions

List instructions

keystone instructions list
keystone instructions list --status pending_match

Submit an instruction interactively

keystone instructions submit

Walks you through an interactive prompt:

Select your role (seller/buyer)
Enter party details (name, reference, wallet)
Enter leg details (instrument, quantity)
Select template
Optionally enter a trade reference to match
Confirm and submit

Activity Logs

Tail your platform’s activity log:

keystone logs
keystone logs --follow     # Continuous polling
keystone logs --limit 50

Example output:

04:15  INFO   settlement.created              Settlement TRADE-2026-0042 initiated
04:18  INFO   compliance.pass                 Compliance check passed (2 checks)
04:21  INFO   settlement.registered_on_chain  Escrow registered, awaiting deposits

Scaffold a Project

Generate a working starter project:

keystone init --template nextjs my-settlement-app

Creates a Next.js project with:

/api/keystone/session - Session token endpoint
/api/webhooks/keystone - Webhook handler with signature verification
/settlements - Settlement list page using @keystoneos/react
/settlements/[id] - Settlement detail page
.env.local.example with required environment variables

Configuration

Credentials are stored in ~/.keystone/config.json:

{
  "credentials": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  },
  "environment": "production"
}

Environment	API URL
`production`	`https://api.keystoneos.xyz`
`staging`	`https://api-staging.keystoneos.xyz`
`development`	`https://api-dev.keystoneos.xyz`

Overview

Backend SDKs

Frontend Library

Tools

Installation

Webhook Forwarding

Settlements

List settlements

Get settlement detail

Instructions

List instructions

Submit an instruction interactively

Activity Logs

Scaffold a Project

Configuration

​Installation

​Login

​Webhook Forwarding

​Settlements

​List settlements

​Get settlement detail

​Instructions

​List instructions

​Submit an instruction interactively

​Activity Logs

​Scaffold a Project

​Configuration

Installation

Login

Webhook Forwarding

Settlements

List settlements

Get settlement detail

Instructions

List instructions

Submit an instruction interactively

Activity Logs

Scaffold a Project

Configuration