docs: add WDK CLI documentation by ihsraham · Pull Request #190 · tetherto/wdk-docs

ihsraham · 2026-06-30T06:19:23Z

Summary

add a dedicated WDK CLI section at /cli with installation, configuration, a complete 31-command API reference, six task guides, and three architecture/security references
document the published @tetherto/wdk-cli@1.0.0-beta.1 package, all three installed binaries, all nine MCP tools, and the current --json / error behavior
document the current security model and recovery contract: local permissions, seed encryption and memory lifetime, absolute TTL, same-user daemon access, and standalone seed.enc v1 recovery
update navigation, related AI pages, the changelog, llms.txt, and llms-full.txt for the new /cli routes

Source baseline

rebased onto develop at 8b7ad75
reviewed against tetherto/wdk-cli@v1.0.0-beta.1, source SHA 74afd9c
verified a clean global install of the scoped npm package; the unscoped wdk-cli package is not this project

Current behavior documented as-is

seed.enc and daemon.pid use 0600; daemon.sock uses 0700; config.json is plaintext with no owner-only guarantee
an unlocked wallet trusts processes running as the same OS user that can reach the daemon; wallet activity does not refresh its absolute TTL
seed.enc v1 uses AES-256-GCM with the documented scrypt parameters and remains recoverable without WDK CLI; automated migration to a future format is not promised
beta.1 permits an empty passphrase and has documented JSON/text/stderr exceptions, including interactive prompt output

This PR changes documentation only; it does not change CLI runtime behavior.

Validation

git diff --check
npm run check:meta
npm run check:redirects
LINK_CHECK_EXTERNAL=false npm run check:links — 272 pages, 2,355 links, zero errors
npm run test:llm-md — 12/12 passed
PATH=/opt/homebrew/opt/node@22/bin:$PATH npm run build
PATH=/opt/homebrew/opt/node@22/bin:$PATH LINK_CHECK_EXTERNAL=false npm run quality
isolated install of @tetherto/wdk-cli@1.0.0-beta.1, version/binary verification, and all 31 leaf --help surfaces
standalone recovery tests: strong and empty passphrases succeeded; wrong passphrase, modified tag, malformed hex, wrong field length, unsupported version, and non-interactive input failed as intended; pseudo-terminal check confirmed hidden passphrase input
independent source-accuracy, security/recovery, IA, and render-safety reviews

Known validation limit

Windows named-pipe behavior was reviewed from source but not runtime-tested on Windows

quocle108 · 2026-07-30T03:07:47Z

+Changing or resetting a key under `networks` locks all wallets so the next unlock initializes WDK with the new wallet-module configuration. `config reset --all` also locks all wallets.
+
+## Indexer
+


it covers how to set the values but not why or where to get them. We should cover these topics:

What it's for: only wdk get history uses the Indexer API

Getting a key: link to the existing Indexer API → Get Started page

Two wiring patterns:

Direct: default baseUrl + your key: wdk config set --key indexer.apiKey --value (or WDK_INDEXER_API_KEY to avoid persisting it).

Proxy: point baseUrl at your own endpoint and leave apiKey empty; your proxy injects the key server-side. Useful for teams that don't want keys on developer machines. The proxy must accept: GET {baseUrl}/api/v1/{chain}/{token}/{address}/token-transfers?limit&fromTs&toTs

Thanks, addressed in 3a4c10f. The section now explains when the Indexer is used, links to key setup, and covers both direct and proxy wiring. It also lists both request forms used by the current CLI.

quocle108 · 2026-07-30T03:23:05Z

+`WDK_INDEXER_BASE_URL` is not read by beta.1.
+
+## MoonPay
+


Same for the MoonPay section. We should cover these topics:

What it's for: wdk buy and wdk sell build a MoonPay widget URL for the selected wallet address and open it in the browser. The transaction happens on MoonPay's side, under your own MoonPay account

apiKey: your publishable MoonPay key (pk_test_… / pk_live_…) from the MoonPay dashboard. It is not the secret key.

signUrl: MoonPay requires widget URLs to be signed with your secret key. The CLI never stores the secret — you run a small signing service and the CLI calls it. See MoonPay LINK

environment: sandbox with pk_test_ for testnets, production with pk_live_ for mainnets

Updated in 3a4c10f. The MoonPay section now covers the publishable key, signing-service request and response, environment pairing, and the current beta.1 behavior where the CLI prints the signed URL for the user to open.

quocle108 · 2026-07-30T03:57:45Z

+<Callout type="warn">
+Use a dedicated development wallet with limited funds. On Unix-like systems, while a wallet is unlocked, any process running as the same OS user that can connect to the owner-only daemon socket can request signing or sending without another passphrase.
+</Callout>
+


We should also explain which CLI capabilities are not exposed over MCP, and why: an agent can operate a wallet a human has unlocked, but can never unlock, export, or reconfigure one.

wallet create/import/export/unlock/lock/delete/rename/default
Why: They handle secrets (seed phrase, passphrase) and require interactive input. Unlocking is deliberately the human authorization moment

config set/reset, network create/delete, token add/delete
Why: They mutate persistent local configuration; these are user-driven decisions

Covered in 3a4c10f. The guide now lists the wallet and configuration operations that are not exposed through wdk-mcp, explains why they remain user-driven, and notes that separate shell access is outside this boundary.

quocle108 · 2026-07-30T03:59:02Z

+The TTL is absolute from unlock; MCP activity does not extend it. Use a short TTL during development and lock the wallet when the session ends.
+
+## Configure A Supported AI Client
+


wdk mcp setup covers Claude Desktop, Claude Code, and OpenClaw, but the server is a standard stdio MCP server (wdk-mcp, installed on PATH), so any MCP-compatible client can use it. We should add an "Other MCP clients" as following

{
"mcpServers": {
"wdk-wallet": {
"command": "wdk-mcp"
}
}
}

Added in 3a4c10f. The guide now includes the generic wdk-mcp stdio configuration and the PATH caveat for clients that do not inherit the shell environment.

quocle108 · 2026-07-30T08:31:32Z

+WDK CLI requires Node.js 22.18.0 or later.
+
+```bash title="Terminal"
+npm install -g @tetherto/wdk-cli@1.0.0-beta.1


pls use this temporary fixed for postinstall

npm install -g --allow-scripts=@tetherto/wdk-cli @tetherto/wdk-cli@1.0.0-beta.1

Applied in 3a4c10f. Both install examples now use the temporary --allow-scripts command.

ihsraham · 2026-07-30T11:55:22Z

Addressed the current CLI docs review feedback in 3a4c10f:

updated both install examples with the temporary --allow-scripts command
expanded Indexer direct/proxy setup, including both history request forms
documented MoonPay publishable keys, signing-service contract, environment pairing, and the actual printed-URL behavior
documented the MCP tool boundary and generic stdio client configuration
rebuilt Get Started around a 12-word wallet, explicit passphrase prompts, Ethereum mainnet funding through MoonPay, send as the primary path, optional --dry-run, and --ttl 0
regenerated and checked public/llms-full.txt; public/llms.txt remains unchanged because routes and titles did not change

Validation: the Node 22 production build passed with 278 static pages, LLM output checks, and 0 broken links. After the final wording-only review fixes, all five changed MDX pages compiled, metadata and internal/anchor link checks passed (2,360 links, 0 errors), git diff --check passed, and the five CLI sections matched public/llms-full.txt exactly.

I left the review threads open for reviewer confirmation.

quocle108 · 2026-07-30T14:47:42Z

@@ -0,0 +1,187 @@
+---
+title: Get Started


In my opinion, I'd like to revert the Get Started direction: the previous Sepolia version was right.
the new flow makes a MoonPay API and MoonPay signing service prerequisites for the getting-started guide. MoonPay is an optional integration - only buy/sell use it, so the quickstart shouldn't require configuring an optional feature

Addressed in c8e7258. I removed MoonPay and the signing-service prerequisites from Get Started. Following Lokesh’s direction, the guide remains on Ethereum mainnet and now uses an external transfer to fund the wallet. Leaving this open for your review.

quocle108

LGTM

ihsraham marked this pull request as ready for review June 30, 2026 07:06

ihsraham marked this pull request as draft June 30, 2026 07:06

ihsraham added 4 commits July 28, 2026 18:59

docs: add WDK CLI documentation

5ed79f7

docs: adjust AI navigation order

50da1aa

docs: refresh WDK CLI draft against merged source

ee5e3fa

docs: complete WDK CLI documentation

1eaed45

ihsraham force-pushed the feat/wdk-cli-docs-draft branch from 90526ac to 1eaed45 Compare July 28, 2026 14:06

quocle108 reviewed Jul 30, 2026

View reviewed changes

quocle108 requested changes Jul 30, 2026

View reviewed changes

docs: address WDK CLI review feedback

3a4c10f

ihsraham marked this pull request as ready for review July 30, 2026 12:00

ihsraham requested a review from quocle108 July 30, 2026 13:24

quocle108 reviewed Jul 30, 2026

View reviewed changes

ihsraham mentioned this pull request Jul 31, 2026

Document July WDK releases and module updates #212

Merged

docs: simplify CLI mainnet quickstart

c8e7258

quocle108 approved these changes Aug 3, 2026

View reviewed changes

Merge upstream/develop into feat/wdk-cli-docs-draft

9a6137a

jonathunne approved these changes Aug 3, 2026

View reviewed changes

ihsraham merged commit 9714421 into tetherto:develop Aug 3, 2026
3 checks passed

This was referenced Aug 3, 2026

Document UTEXO RGB Lightning wallet module #216

Merged

Release develop docs updates to main #222

Merged

		Changing or resetting a key under `networks` locks all wallets so the next unlock initializes WDK with the new wallet-module configuration. `config reset --all` also locks all wallets.

		## Indexer

		The TTL is absolute from unlock; MCP activity does not extend it. Use a short TTL during development and lock the wallet when the session ends.

		## Configure A Supported AI Client

Uh oh!

Conversation

ihsraham commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Source baseline

Current behavior documented as-is

Validation

Known validation limit

Uh oh!

quocle108 Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quocle108 Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ihsraham commented Jul 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quocle108 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ihsraham commented Jun 30, 2026 •

edited

Loading

quocle108 Jul 30, 2026 •

edited

Loading

quocle108 Jul 30, 2026 •

edited

Loading