@settlemint/dalp-cli 3.1.18-release.34270626122 → 3.1.19-main.34482536277

package/README.md

@@ -8,197 +8,71 @@
   </p>
 </p>
 
-<p align="center">
-<a href="https://www.npmjs.com/package/@settlemint/dalp-cli" rel="nofollow"><img src="https://img.shields.io/npm/v/@settlemint/dalp-cli" alt="npm version"></a>
-<a href="https://www.npmjs.com/package/@settlemint/dalp-cli" rel="nofollow"><img src="https://img.shields.io/npm/dw/@settlemint/dalp-cli" alt="npm downloads"></a>
-</p>
-
-<div align="center">
-  <a href="https://settlemint.com">Website</a>
-  <span>&nbsp;&nbsp;&bull;&nbsp;&nbsp;</span>
-  <a href="https://www.npmjs.com/package/@settlemint/dalp-cli">NPM</a>
-  <span>&nbsp;&nbsp;&bull;&nbsp;&nbsp;</span>
-  <a href="mailto:support@settlemint.com">Support</a>
-  <br />
-</div>
-
 ## About
 
-The DALP CLI provides a command-line interface for interacting with the Digital Asset Lifecycle Platform. Manage security tokens, identities, compliance, and platform operations directly from the terminal — or let your AI agent do it for you.
+kubectl-style CLI over the public promise-based `@settlemint/dalp-sdk`.
 
-## Installation
+Command paths come from the **OpenAPI URL** (static segments) plus the HTTP verb:
 
-```bash
-# npm
-npm install -g @settlemint/dalp-cli
+| HTTP   | URL                                       | CLI                                                  |
+| ------ | ----------------------------------------- | ---------------------------------------------------- |
+| `GET`  | `/api/v2/tokens`                          | `dalp get tokens`                                    |
+| `GET`  | `/api/v2/tokens/{assetId}`                | `dalp get tokens <assetId>`                          |
+| `GET`  | `/api/v2/tokens/{tokenAddress}/documents` | `dalp get tokens documents <tokenAddress>`           |
+| `POST` | `/api/v2/tokens/{tokenAddress}/mints`     | `dalp create tokens mints <tokenAddress> --body '…'` |
 
-# bun
-bun add -g @settlemint/dalp-cli
-```
+OpenAPI text is extracted at **compile time** (`bun run codegen`) into
+`src/generated/openapi-surface.json` and drives help, args, options, enums,
+examples, and hints for agents (Incur `--llms` / MCP / skills).
 
-## Quick Start
+## Setup
 
 ```bash
-# Authenticate (OAuth 2.0 device flow — no passwords in your terminal)
+dalp config set apiUrl https://dalp.example.com
 dalp login
-
-# Show current user
+dalp org switch org_…
 dalp whoami
-
-# List all tokens
-dalp tokens list --format json
 ```
 
-## Worked Examples
-
-End-to-end flows you can run as-is. Add `--format json` to any command for machine-readable output.
-
-### Authenticate and inspect the platform
+## Examples
 
 ```bash
-# Authenticate against a specific instance (or set DALP_URL)
-dalp login --url https://dalp.example.com
-
-# Confirm who you are and which organization is active
-dalp whoami
-
-# List deployed systems, then the tokens they hold
-dalp system list
-dalp tokens list --format json
+dalp get tokens --help
+dalp get tokens index --sort name --limit 25
+dalp get tokens documents index 0x…
+dalp create tokens mints 0x… --body '{"recipients":[…],"amounts":[…]}'
+# Mutations ask the platform to hold the response until settlement (TTY spinner + status).
+# Agents get streamed status events either way.
+dalp create tokens mints 0x… --body '…' --no-wait
 ```
 
-Expected outcome: a stored API key in your keychain, your user and organization echoed back, and a token inventory in JSON.
+## Status UX (Incur best practices)
 
-> SDK equivalent: `createDalpClient` with `dalp.token.list()` and `dalp.system.read()` — see the [`@settlemint/dalp-sdk` README](../sdk/README.md).
+Long-running work uses `async *run` generators ([Incur Streaming](https://github.com/wevm/incur#streaming)):
 
-### Create an asset and verify it round-trip
+- **Humans (TTY):** braille spinner on stderr with clear phase messages (`Preparing…`, `Submitting METHOD /url…`, `Waiting for settlement…`).
+- **Agents (`c.agent`):** structured yields `{ phase, message, status? }` with no spinner noise on stdout.
+- **Blockchain mutations:** the wait belongs to the platform, not the CLI. The default asks it to hold the response until the write settles; `--no-wait` asks it to answer immediately. Either way the command reports what came back, and a write that outlives the wait prints `Request accepted; the transaction is still settling` with the handle. Follow that handle with `dalp get transaction-requests stream <transactionId>`; the CLI does not poll it for you.
+- **SSE endpoints** (`…/stream`): each Server-Sent Event is yielded as a chunk. Use `--format jsonl` for NDJSON (`{"type":"chunk","data":…}`).
+- **Errors:** public `message` stays the headline; `why` / `fix` and mapped resource `links` become an Incur CTA (`meta.cta`) so agents get next commands without scraping free text.
+- **Success links:** JSON:API `links` (`next` / `prev` / related) map to suggested CLI commands when present.
 
 ```bash
-# Create a bond token (type-specific fields go in --json)
-dalp tokens create --name "Bund 7Y" --symbol BUND7 --decimals 18 --type bond --country-code 276 --json '{"isin":"DE000BU27014"}'
-
-# Find it in the token list (filterable by search query)
-dalp tokens list --query BUND7
-
-# Read its details and holder list by contract address
-dalp tokens read <address>
-dalp tokens holders <address>
-```
-
-Expected outcome: a new bond token deployed through the platform, retrievable by address with an empty holder list.
-
-> SDK equivalent: the typed `dalp.token.*` namespace in [`@settlemint/dalp-sdk`](../sdk/README.md).
-
-### Register an investor identity and run KYC
-
-```bash
-# Create an on-chain identity for a wallet, then register it with a country code
-dalp identities create --wallet 0x1234...abcd
-dalp identities register --wallet 0x1234...abcd --country 276
-
-# Check the registration landed
-dalp identities registration-status 0x1234...abcd
-
-# Start a KYC submission for the user and send it for review
-dalp kyc version-create <userId>
-dalp kyc version-submit --version-id <versionId>
+dalp get transaction-requests stream <transactionId>
+dalp get tokens create stream <transactionId>
+dalp get actions stream
+dalp get monitoring api request-logs stream
 ```
 
-Expected outcome: a registered on-chain identity for the wallet and a KYC version in review.
-
-> SDK equivalent: `dalp.system.identity.*` and `dalp.user.kyc.*` in [`@settlemint/dalp-sdk`](../sdk/README.md).
-
-### Using the CLI from an AI agent
-
-Every command accepts `--format json` (also `yaml`, `md`, `jsonl`; the default is token-efficient TOON) and a `--json` shorthand, so output is always machine-parseable. Authentication is interactive by design: `dalp login` runs an OAuth 2.0 device flow in a browser, then persists an API key to the system keychain — subsequent commands, including agent-driven ones, run non-interactively against that stored credential. Instance and organization can be pinned via the `DALP_URL` and `DALP_ORG` environment variables.
-
-## AI Agent Integration
-
-The CLI is built from the ground up for AI agents. Every command is a typed, validated tool that agents can discover and call autonomously.
-
-### Model Context Protocol (MCP)
-
-Run the CLI as an MCP server, exposing every command as a tool with Zod-validated parameters, descriptions, and examples:
-
-```bash
-# Auto-register with your AI agent (Claude Code, Cursor, Codex, OpenClaw)
-dalp mcp add
-
-# Or run the MCP server directly
-dalp --mcp
-```
-
-### Skills
-
-Auto-generate skill files from command metadata for agent discovery:
-
-```bash
-# Install skill files for your agent
-dalp skills add
-
-# View as Markdown or JSON Schema
-dalp --llms
-dalp --schema
-```
-
-### Structured Output
-
-Every command supports `--format json` for machine-readable output, making it composable with shell tools and agent workflows:
-
-```bash
-# Progressive discovery: systems → tokens → holders
-dalp system list --format json
-dalp tokens list --format json
-dalp tokens holders <address> --format json
-```
+## Architecture
 
-### Supported Agents
-
-Auto-detection and one-command setup for Claude Code, Codex Desktop, Cursor, and OpenClaw.
-
-## Commands
-
-| Command                   | Description                         |
-| ------------------------- | ----------------------------------- |
-| `login`                   | Authenticate with the DALP platform |
-| `logout`                  | End the current session             |
-| `whoami`                  | Show the current authenticated user |
-| `tokens`                  | Manage security tokens              |
-| `token-sales`             | Manage token sales                  |
-| `tokens documents`        | Manage token-related documents      |
-| `identity`                | Manage on-chain identities          |
-| `identity-recoveries`     | Recover lost identities             |
-| `kyc`                     | Manage KYC verification             |
-| `compliance-templates`    | Manage compliance templates         |
-| `asset-type-templates`    | Manage asset type templates         |
-| `user`                    | Manage platform users               |
-| `contacts`                | Manage contacts                     |
-| `account`                 | Manage accounts                     |
-| `admin`                   | Administrative operations           |
-| `auth`                    | Authentication configuration        |
-| `config`                  | CLI configuration                   |
-| `exchange-rates`          | View exchange rates                 |
-| `external-tokens`         | Manage external tokens              |
-| `fixed-yield-schedules`   | Manage fixed yield instruments      |
-| `monitoring`              | Platform monitoring                 |
-| `search-results`          | Search across the platform          |
-| `settings`                | Platform settings                   |
-| `system`                  | System administration               |
-| `blockchain-transactions` | View transactions                   |
-| `xvp-settlements`         | Cross-value-payment operations      |
-| `actions`                 | Manage actions                      |
-
-## Security
-
-- **OAuth 2.0 Device Authorization Grant** (RFC 8628) — no passwords in your terminal
-- Credentials stored in system keychain (macOS) or encrypted file (Linux/Windows)
-- API key auto-creation during login
-- Agents operate with your user permissions only
-
-## Configuration
-
-The CLI resolves configuration from (in order): CLI flags, environment variables, project config (`.dalprc.json`), and user config (`~/.config/dalp/`).
+| Concern   | Implementation                                                     |
+| --------- | ------------------------------------------------------------------ |
+| Framework | Incur + Zod                                                        |
+| HTTP      | `createDalpClient` + route ids from `@settlemint/dalp-sdk/routes`  |
+| Docs      | Compile-time OpenAPI surface (`bun run codegen`)                   |
+| Auth      | Device login → API key; `X-Organization-Id` from stored active org |
 
 ## License
 
-This project is licensed under the **SettleMint Commercial Customer Source License**. See the LICENSE file included in the package for full terms.
+See `LICENSE`.