Skip to main content
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

​
Login

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:
  1. Creates a temporary webhook endpoint on KeyStone
  2. Polls for new events
  3. Forwards each event to your local server via HTTP POST
  4. Shows events in your terminal with colored output
  5. Cleans up the temporary endpoint on exit (Ctrl+C)
Example output: 
✓ Listening for webhooks...
  Forwarding to: http://localhost:3000/webhooks/keystone

12:04:15  settlement.state.compliance_cleared  stl-a1b2c3d4  → 200 OK (42ms)
12:04:18  settlement.state.awaiting_deposits   stl-a1b2c3d4  → 200 OK (38ms)
12:05:02  settlement.state.finalized           stl-a1b2c3d4  → 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:
  1. Select your role (seller/buyer)
  2. Enter party details (name, reference, wallet)
  3. Enter leg details (instrument, quantity)
  4. Select template
  5. Optionally enter a trade reference to match
  6. Confirm and submit

​
Activity Logs

Tail your platform’s activity log: 
keystone logs
keystone logs --follow     # Continuous polling
keystone logs --limit 50
Example output: 
12:04:15  INFO   settlement.created    Settlement TRADE-2026-0042 initiated
12:04:16  INFO   compliance.started    Screening 2 parties
12:04:18  INFO   compliance.cleared    All parties passed

​
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"
}
EnvironmentAPI URL
productionhttps://api.keystoneos.xyz
staginghttps://api-staging.keystoneos.xyz
developmenthttps://api-dev.keystoneos.xyz