npm package: @holotest/waap-cli
Description: CLI for AI agents to authenticate and interact with the WaaP wallet
Latest version: 0.1.16

# @human.tech/waap-cli

A CLI for AI agents to authenticate and sign/submit transactions using the **WaaP wallet** on both **EVM** and **Sui** chains — no browser required.

## Installation

```bash
npm install -g @human.tech/waap-cli
# or run without installing
npx @human.tech/waap-cli --help
```

## AI Agent Skills (skills.sh)

This package ships with a native `skills.sh`-compatible skill definition. If your AI agent (Cursor, Copilot, Cline, etc.) supports local agent skills, it will automatically discover the `SKILL.md` rules inside the `@human.tech/waap-cli` npm package when installed in your workspace.

Agents can also install the standalone skill directly from its repository using the [Skills CLI](https://skills.sh/):

```bash
npx skills add https://github.com/holonym-foundation/waap-cli-skills
```

## Supported Chains

waap-cli supports two chain families:

- **EVM** — Ethereum, Base, Polygon, Arbitrum, and any EVM-compatible chain
- **Sui** — Sui mainnet, testnet, devnet, and localnet

Chain is specified with the `--chain` flag using the format:

- EVM: `evm:<chainId>` (e.g., `evm:1`, `evm:8453`, `evm:137`) or just the chain ID (e.g., `1`)
- Sui: `sui:<network>` (e.g., `sui:mainnet`, `sui:testnet`, `sui:devnet`, `sui:localnet`)

You can also set a default chain so you don't have to pass `--chain` every time:

```bash
waap-cli chain set evm:1 --rpc https://eth.llamarpc.com
waap-cli chain set sui:mainnet
waap-cli chain get   # show current default
```

## Commands

### `signup`

Create a new WaaP wallet account and immediately log in.

```bash
waap-cli signup --email youremail+agent007@example.com --password 'S3cur3Pass!'
# optional display name:
waap-cli signup --email youremail+agent007@example.com --password 'S3cur3Pass!' --name "My Agent 007"
```

_Note: To create multiple agent accounts, use different email addresses with the + alias syntax (e.g., "youremail+agent001@example.com", "youremail+agent002@example.com", etc.)._

### `login`

Authenticate with an existing account and save a local session.

```bash
waap-cli login --email youremail+agent007@example.com --password 'S3cur3Pass!'
```

### `whoami`

Print the wallet addresses derived from the current session's keyshare. Shows both EVM and Sui addresses.

```bash
waap-cli whoami
# → EVM Wallet address: 0xAbc...
# → Sui Wallet address: 0x123...
```

### `session-info`

Inspect the raw metadata stored in `~/.waap-cli/session.json`.

```bash
waap-cli session-info
```

### `logout`

Delete the local session file.

```bash
waap-cli logout
```

### `chain get`

Show the current default chain and RPC.

```bash
waap-cli chain get
```

### `chain set`

Set the default chain and optionally the RPC URL.

```bash
waap-cli chain set evm:1 --rpc https://eth.llamarpc.com
waap-cli chain set sui:mainnet
```

---

### `sign-message`

Sign an arbitrary message. Works on both EVM and Sui.

**EVM** — Signs using EIP-191 (`personal_sign` format). Accepts plain text or `0x`-prefixed hex. Returns a hex signature.

```bash
waap-cli sign-message --message "Hello WaaP"
waap-cli sign-message --message 0x48656c6c6f
# with explicit chain:
waap-cli sign-message --message "Hello" --chain evm:1
# bypass 2FA:
waap-cli sign-message --message "Hello" --permission-token <encoded-pt>
```

**Sui** — Signs using Blake2b hashing. Returns a Base64-encoded signature and message bytes.

```bash
waap-cli sign-message --message "Hello Sui" --chain sui:mainnet
```

### `sign-typed-data` (EVM only)

Sign EIP-712 typed data (`eth_signTypedData_v4`). Pass the full typed-data object as a JSON string.

```bash
waap-cli sign-typed-data --data '{
  "types": {
    "EIP712Domain": [{"name":"name","type":"string"}],
    "Mail": [{"name":"contents","type":"string"}]
  },
  "domain": {"name":"Ether Mail","chainId":1},
  "primaryType": "Mail",
  "message": {"contents":"Hello!"}
}'
```

---

### `sign-tx`

Sign a transaction and print the result **without broadcasting**.

**EVM** — Returns a raw `0x`-prefixed hex string ready for `eth_sendRawTransaction`.

```bash
# EIP-1559 (default) — ETH transfer
waap-cli sign-tx \
  --to 0xRecipientAddress \
  --value 0.01 \
  --chain evm:1 \
  --rpc https://eth.llamarpc.com

# Contract interaction (e.g. ERC-20 approve)
waap-cli sign-tx \
  --to 0xTokenContract \
  --value 0 \
  --data 0x095ea7b3... \
  --chain evm:1 \
  --rpc https://eth.llamarpc.com

# Legacy (Type 0) — for chains that don't support EIP-1559
waap-cli sign-tx \
  --to 0xRecipientAddress \
  --value 0.01 \
  --chain evm:1 \
  --legacy \
  --rpc https://eth.llamarpc.com
```

**Sui** — Returns a Base64-encoded signature and transaction bytes.

```bash
# Simple SUI transfer (value in MIST)
waap-cli sign-tx \
  --to 0xRecipientSuiAddress \
  --value 1000 \
  --chain sui:mainnet

# Pre-built BCS-encoded transaction bytes
waap-cli sign-tx \
  --tx-bytes <base64-bcs-bytes> \
  --chain sui:mainnet

# JSON-serialized TransactionBlock
waap-cli sign-tx \
  --tx-json '<json-string>' \
  --chain sui:testnet
```

### `send-tx`

Build, sign, and **broadcast** a transaction in one step.

**EVM** — Returns a transaction hash.

```bash
# ETH transfer on mainnet
waap-cli send-tx \
  --to 0xRecipientAddress \
  --value 0.01 \
  --chain evm:1 \
  --rpc https://eth.llamarpc.com

# Transfer on Base
waap-cli send-tx \
  --to 0xRecipientAddress \
  --value 0.001 \
  --chain evm:8453 \
  --rpc https://mainnet.base.org

# ERC-20 transfer via calldata
waap-cli send-tx \
  --to 0xTokenContract \
  --value 0 \
  --data 0xa9059cbb... \
  --chain evm:1 \
  --rpc https://eth.llamarpc.com

# Legacy (Type 0) transaction
waap-cli send-tx \
  --to 0xRecipientAddress \
  --value 0.01 \
  --chain evm:1 \
  --legacy \
  --rpc https://eth.llamarpc.com
```

**Sui** — Returns a transaction digest.

```bash
# Simple SUI transfer (value in MIST)
waap-cli send-tx \
  --to 0xRecipientSuiAddress \
  --value 1000 \
  --chain sui:mainnet

# Pre-built BCS-encoded transaction bytes
waap-cli send-tx \
  --tx-bytes <base64-bcs-bytes> \
  --chain sui:mainnet

# JSON-serialized TransactionBlock
waap-cli send-tx \
  --tx-json '<json-string>' \
  --chain sui:testnet
```

---

### `request` (EVM only)

Generic EIP-1193 JSON-RPC interface. Takes optional params as a JSON array string.

```bash
# Get wallet address
waap-cli request eth_accounts

# Get chain ID
waap-cli request eth_chainId

# Get ETH balance
waap-cli request eth_getBalance '["0xYourAddress","latest"]' --chain-id 1 --rpc https://eth.llamarpc.com

# Sign a message (personal_sign)
waap-cli request personal_sign '["0x48656c6c6f20576161502021","0xYourAddress"]'

# EIP-712 typed data sign
waap-cli request eth_signTypedData_v4 '["0xYourAddress","{\"types\":{...},\"domain\":{...},\"primaryType\":\"Mail\",\"message\":{...}}"]'

# Send transaction via EIP-1193
waap-cli request eth_sendTransaction \
  '[{"from":"0xYourAddress","to":"0xRecipient","value":"0x2386F26FC10000","chainId":"0x1"}]' \
  --chain-id 1 --rpc https://eth.llamarpc.com
```

---

### `policy get`

Show current wallet policy settings.

```bash
waap-cli policy get
# →
# Policy Settings:
#    2FA Method:        EMAIL_AUTHZ
#    Daily Spend Limit: $100
#    Min Risk for 2FA:  HighWarn
```

### `policy set`

Update wallet policy settings. Currently supports `--daily-spend-limit`.

```bash
# Set daily spend limit to $500 (requires 2FA approval if enabled)
waap-cli policy set --daily-spend-limit 500
```

Valid range: 0-10,000 USD. The limit is floored to the nearest integer.

### `2fa status`

View the current Two-Factor Authentication method configured for the wallet.

```bash
waap-cli 2fa status
```

### `2fa enable`

Enable 2FA using email, phone, Telegram, or an external hardware wallet.

```bash
# Email 2FA
waap-cli 2fa enable --email agent@example.com

# Phone 2FA
waap-cli 2fa enable --phone "+1234567890"

# Telegram 2FA
waap-cli 2fa enable --telegram 7381029636

# External wallet (hardware wallet) 2FA
waap-cli 2fa enable --wallet 0xHardwareWalletAddress
```

If an existing 2FA method is already active, enabling a new one is a **2-step flow**:

1. approve with your current method, then
2. verify the new method.

### `2fa disable`

Disable 2FA, allowing autonomous signing without out-of-band approval.

```bash
waap-cli 2fa disable
```

> Warning: Disabling 2FA requires approval from the currently-configured 2FA method before taking effect.

## How it works

1. **Login** — email + password -> JWT (no cookies, no browser)
2. **Keyshare** — fetched from the keyshare-manager and AES-GCM decrypted with `userKey`
3. **Signing** — 2-party ECDSA (WASM + policy-engine over HTTP)
4. **Address derivation** — EVM uses uncompressed secp256k1 public key; Sui uses compressed secp256k1 public key

> **2FA:** Newly created accounts start with Authorization Method set to `Disabled`.
> To manage 2FA: `waap-cli 2fa status/enable/disable`. To bypass 2FA programmatically, pass `--permission-token`.

## RPC

**EVM:** For `eth_getBalance`, `send-tx`, and `sign-tx`, RPC can be passed with `--rpc`. The CLI will auto-select a free public RPC if `--rpc` is not set. Free public RPCs may not be reliable for production use.

**Sui:** The CLI uses `@mysten/sui`'s `getFullnodeUrl()` by default based on the network (mainnet, testnet, devnet, localnet). Custom RPC can also be set via `--rpc` or `chain set`.

## EVM vs Sui Quick Reference

| Feature | EVM | Sui |
|---------|-----|-----|
| Chain flag | `--chain evm:<chainId>` | `--chain sui:<network>` |
| Value unit | ETH (e.g., `0.01`) | MIST (e.g., `1000`) |
| Tx input | `--to`, `--value`, `--data` | `--to`/`--value`, `--tx-bytes`, or `--tx-json` |
| Signature format | Hex string | Base64 string |
| Address format | 0x (20 bytes) | 0x (32 bytes) |
| RPC default | Public RPC fallback | `getFullnodeUrl()` |
| Typed data | `sign-typed-data` (EIP-712) | N/A |
| Legacy tx | `--legacy` flag | N/A |