npm package: @human.tech/waap-cli
Description: CLI for AI agents to authenticate and interact with the WaaP wallet
Latest version: 0.1.6

# @human.tech/waap-cli

A CLI for AI agents to authenticate and sign/submit transactions using the **WaaP wallet** — 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
```

## 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 address derived from the current session's keyshare.

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

### `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
```

### `sign-message`

Sign an arbitrary message using EIP-191 (`personal_sign` format). Accepts plain text or `0x`-prefixed hex.

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

### `sign-typed-data`

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 an EVM transaction and print the raw signed hex **without broadcasting**.\nUseful for offline signing, review before broadcast, or custom relay flows.

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

# Specific chain (Base)
waap-cli sign-tx \
  --to 0xRecipientAddress \
  --value 0.001 \
  --chain-id 8453 \
  --rpc https://mainnet.base.org

# Contract interaction (e.g. ERC-20 approve)
waap-cli sign-tx \
  --to 0xTokenContract \
  --value 0 \
  --data 0x095ea7b3000000000000000000000000SpenderPadded00000000000000000000000Amount \
  --chain-id 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-id 1 \
  --legacy \
  --rpc https://eth.llamarpc.com
```

The output is a raw `0x`-prefixed hex string ready to be broadcast with `eth_sendRawTransaction`.

### `send-tx`

Build, sign, and **broadcast** an EVM transaction in one step.

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

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

# ERC-20 transfer via calldata (no ETH value)
waap-cli send-tx \
  --to 0xTokenContract \
  --value 0 \
  --data 0xa9059cbb000000000000000000000000RecipientPadded000000000000000000000000Amount \
  --chain-id 1 \
  --rpc https://eth.llamarpc.com

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

### `request`

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) — message as 0x hex, then address
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 — a verification link is sent to the provided address
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
```

> ⚠️ 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)

> **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

For `eth_getBalance`, `send-tx`, and `sign-tx`, RPC must be passed with `--rpc` option flag.

The waap-cli will auto select a free public RPC url if `--rpc` option flag is not set.

Please note that the free public RPC url may not be reliable for production use.