> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Command-line tool for development, debugging, and webhook forwarding.

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

```bash theme={null}
npm install -g @keystoneos/cli
```

Or use without installing:

```bash theme={null}
npx @keystoneos/cli login
```

<Note>
  [Source on GitHub](https://github.com/KeyStone-OS/keystone-cli)
</Note>

## Login

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

```bash theme={null}
keystone login
```

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

```bash theme={null}
keystone login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
```

Set the environment (default: production):

```bash theme={null}
keystone login --environment staging
```

***

## Webhook Forwarding

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

```bash theme={null}
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  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

```bash theme={null}
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

```bash theme={null}
keystone settlements get a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

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

***

## Instructions

### List instructions

```bash theme={null}
keystone instructions list
keystone instructions list --status pending_match
```

### Submit an instruction interactively

```bash theme={null}
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:

```bash theme={null}
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:18  INFO   compliance.pass                 Compliance check passed (2 checks)
12:04:21  INFO   settlement.registered_on_chain  Escrow registered, awaiting deposits
```

***

## Scaffold a Project

Generate a working starter project:

```bash theme={null}
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`:

```json theme={null}
{
  "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`     |