cli host

[pgherveou]

What this adds

truapi-host is a native CLI for running TrUAPI without a browser or mobile app. It provides both sides of the host flow:

• a signing host that manages the wallet identity, approvals, allowances, and signatures;
• a pairing host that serves a product, emits a pairing link, and forwards requests to a signing host.

Both roles use the real Paseo Next v2 services, including LitePeople identity, the People-chain Statement Store, and Bulletin preimages.

Get started

Build and install the CLI once, then launch the signing host:

make headless install
truapi-host signing-host

The CLI selects or creates an attested account and waits for ring readiness. If an auto-managed account has no free Statement Store slot during pairing, it retries with another account. From the command bar you can:

• paste a polkadotapp:// pairing link or use /deeplink <link>;
• use /script to create or run a TypeScript product script;
• use /session to keep separate local host profiles;
• use /help to discover the remaining commands and shortcuts.

Product scripts run with Bun and receive a ready-to-use global truapi client. They can import npm dependencies directly; Bun installs missing packages automatically.

#!/usr/bin/env bun

import chalk from "chalk";

const result = await truapi.account.getUserId();
if (!result.isOk()) throw new Error(JSON.stringify(result.error));

console.log(chalk.green("user id:"), result.value);

Run a script directly when an interactive session is unnecessary:

truapi-host signing-host \
  --product-id my-product.dot \
  --script ./script.ts \
  --auto-accept

User experience

• ⌨️ Fast command entry: a persistent command bar with aligned autocomplete, history, and keyboard shortcuts.
• ✨ Clear feedback: quiet sentence-case progress and concise approval prompts, with debug and trace logs available on demand.

End-to-end coverage

The Playground's generated examples are also the headless compatibility suite. The battery discovers and executes all 64 exposed TrUAPI examples.

It is measured independently against both host topologies and writes browser-compatible reports consumed by the compatibility explorer.

Signing host

This command generates explorer/diagnosis-reports/signing-host-cli.md:

target/debug/truapi-host signing-host \
  --product-id truapi-playground.dot \
  --script rust/crates/truapi-host-cli/js/scripts/battery.ts \
  --auto-accept

Pairing host

Start the product-facing host, then answer its emitted link from a signing host. The pairing-host process generates explorer/diagnosis-reports/pairing-host-cli.md when the battery completes:

# Terminal 1
target/debug/truapi-host pairing-host \
  --product-id truapi-playground.dot \
  --script rust/crates/truapi-host-cli/js/scripts/battery.ts \
  --auto-accept

# Terminal 2
target/debug/truapi-host signing-host \
  --deeplink '<pairing link>' \
  --auto-accept

The live coverage exercises pairing, permissions, account and legacy signing, transaction construction, chain RPC, Statement Store proofs and subscriptions, resource allocation, push notifications, and Bulletin preimages. Remaining failures are isolated to the Chat and Payment APIs that are not currently implemented by the host.

The PR also includes Rust unit/integration coverage, generated-client parity checks, and Bun tests for diagnosis discovery and reporting.

[pgherveou]

signing host:

pairing host: