@towns-labs/wallet 7.0.0

package/README.md

@@ -0,0 +1,446 @@
+# towns wallet-cli
+
+CLI for `tw` account onboarding, session key lifecycle, and relayed transactions.
+
+Built on [incur](https://github.com/wevm/incur) — every command supports `--help`, `--json`, `--format`, and can run as an MCP server via `--mcp`.
+
+## Run with bunx
+
+```bash
+bunx @towns-labs/wallet --help
+```
+
+## Permissionless
+
+`tw` is fully permissionless: no signup, no account registration, and no login flow. You can run it immediately with local keys.
+
+## Output Modes
+
+incur handles output formatting automatically:
+
+- `--json` — structured JSON output
+- `--format table` — tabular output
+- Default: human-readable text
+
+## Help and Discovery
+
+```bash
+# Show all commands
+tw --help
+
+# Show help for a specific command
+tw account create --help
+
+# Machine-readable command manifest (for LLMs/agents)
+tw --llms
+
+# Run as an MCP server
+tw --mcp
+
+# Version
+tw --version
+```
+
+## Account Create
+
+Create a new account (interactive password prompt):
+
+```bash
+tw account create
+```
+
+Create a named profile in local dev:
+
+```bash
+tw account create --env dev --profile agent
+```
+
+Keystore layout:
+
+```text
+~/.config/towns/tw/profiles/<env>/<profile>/default.keystore.json
+~/.config/towns/tw/profiles/<env>/<profile>/sessions/<session-name>.json
+```
+
+Resume a previously created profile:
+
+```bash
+tw account create --resume --env dev --profile agent
+```
+
+Non-interactive mode (stdin password + JSON output):
+
+```bash
+echo "my-password" | tw account create --password-stdin --json
+```
+
+Use an explicit keystore path:
+
+```bash
+tw account create --keystore-path ~/.config/towns/tw/profiles/dev/team/default.keystore.json --env dev
+```
+
+## Account Export
+
+Export metadata only (safe default):
+
+```bash
+tw account export --env dev --profile agent
+```
+
+Export metadata in JSON:
+
+```bash
+tw account export --env dev --profile agent --json
+```
+
+Export decrypted private keys (interactive confirmation required):
+
+```bash
+tw account export --env dev --profile agent --show-private
+```
+
+## Account Address
+
+Print the main/root account address:
+
+```bash
+tw account address --env dev --profile agent
+```
+
+## Address (Root Alias)
+
+`tw address` is a root alias for `tw account address` with optional funding display helpers.
+
+Print address + default funding context (USDC on Base):
+
+```bash
+tw address
+```
+
+Show a funding payment link:
+
+```bash
+tw address --link --amount 100
+```
+
+Show a QR for the same payment payload:
+
+```bash
+tw address --qr --amount 100
+```
+
+Custom token amount requires explicit decimals:
+
+```bash
+tw address --token 0x1111111111111111111111111111111111111111 --amount 1 --decimals 18 --link
+```
+
+## Account Balance
+
+Check USDC balance for the main/root account on Base (default):
+
+```bash
+tw account balance --env dev --profile agent
+```
+
+Check USDC balance on Polygon:
+
+```bash
+tw account balance --env prod --profile agent --chain polygon
+```
+
+For local dev (`--env dev`), default chain is Anvil (`http://127.0.0.1:8545`).
+
+## Account Send
+
+Send USDC to an address:
+
+```bash
+tw account send 1 0x1111111111111111111111111111111111111111
+```
+
+Send USDC to ENS on Base:
+
+```bash
+tw account send 2.5 vitalik.eth --chain base
+```
+
+Send USDC on Polygon with JSON output:
+
+```bash
+tw account send 10 0x1111111111111111111111111111111111111111 --chain polygon --env prod --json
+```
+
+Local dev defaults to Anvil:
+
+```bash
+tw account send 1 0x1111111111111111111111111111111111111111 --env dev
+```
+
+## Contacts
+
+Store aliases in a global contacts file:
+
+```text
+~/.config/towns/tw/contacts.json
+```
+
+Add contact aliases:
+
+```bash
+tw contacts add vitalik vitalik.eth
+tw contacts add treasury 0x1111111111111111111111111111111111111111
+```
+
+List or show contacts:
+
+```bash
+tw contacts list --json
+tw contacts show vitalik --json
+```
+
+Update, rename, and remove:
+
+```bash
+tw contacts update vitalik 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+tw contacts rename vitalik vitalik-main
+tw contacts remove vitalik-main
+```
+
+Export and import:
+
+```bash
+tw contacts export --json
+tw contacts import ./contacts.json --json
+tw contacts import ./contacts.json --force --json
+```
+
+Import returns deterministic summary fields:
+
+- `importedCount`
+- `skippedInvalidCount`
+- `skippedConflictCount`
+- `overwrittenCount`
+
+Send via alias:
+
+```bash
+tw account send 10 vitalik
+```
+
+ENS safety behavior for ENS-backed contacts:
+
+- If ENS re-resolution fails, `tw account send` falls back to the stored address.
+- If ENS re-resolution succeeds but points to a different address than stored, send aborts and requires explicit `tw contacts update`.
+
+Send with a portable session file (no root keystore required):
+
+```bash
+tw account send 1 0x1111111111111111111111111111111111111111 \
+  --env prod --chain base --session-file ./worker-1.session.json
+```
+
+## Account Status
+
+Show compact readiness status:
+
+```bash
+tw account status --env dev --profile agent
+```
+
+JSON output for automation:
+
+```bash
+tw account status --env prod --profile agent --chain polygon --json
+```
+
+## Account Update Password
+
+Rotate local keystore encryption password (interactive):
+
+```bash
+tw account update password --env dev --profile agent
+```
+
+Rotate password non-interactively using stdin lines:
+
+```bash
+printf "old-password\nnew-password\n" | tw account update password --current-password-stdin --new-password-stdin --json
+```
+
+## Session Create
+
+Create and authorize a scoped session key in one intent:
+
+```bash
+echo "my-password" | tw session create worker-1 --profile agent --password-stdin --json
+```
+
+Create and activate immediately:
+
+```bash
+echo "my-password" | tw session create worker-2 --profile agent --activate --password-stdin
+```
+
+Resume a previously interrupted create flow:
+
+```bash
+echo "my-password" | tw session create worker-1 --profile agent --resume --password-stdin --json
+```
+
+Grant full wildcard access (explicit opt-in):
+
+```bash
+echo "my-password" | tw session create worker-admin --profile agent --full-access --password-stdin
+```
+
+## Session List
+
+List local sessions:
+
+```bash
+tw session list --profile agent --json
+```
+
+Include on-chain key status:
+
+```bash
+tw session list --profile agent --on-chain --json
+```
+
+## Session Export
+
+Export a session key as a portable file:
+
+```bash
+TW_PASSWORD="my-password" TW_EXPORT_PASSWORD="export-password" \
+  tw session export worker-1 --profile agent --output ./worker-1.session.json
+```
+
+Or provide the export password via stdin:
+
+```bash
+echo "export-password" | tw session export worker-1 --profile agent \
+  --output ./worker-1.session.json --export-password-stdin
+```
+
+## Session Import
+
+Import a portable session as a session-only profile:
+
+```bash
+tw session import ./worker-1.session.json --profile worker-1
+```
+
+This creates:
+
+```bash
+~/.config/towns/tw/profiles/worker-1/session.json
+```
+
+Session-only profiles can execute `account send` but cannot run manager commands that require a root keystore.
+
+## Session Rotate
+
+Rotate the active session (auto-generates new name):
+
+```bash
+echo "my-password" | tw session rotate --profile agent --password-stdin --json
+```
+
+Rotate to an explicit new session name:
+
+```bash
+echo "my-password" | tw session rotate --profile agent --new-name worker-3 --password-stdin
+```
+
+Resume interrupted rotation:
+
+```bash
+echo "my-password" | tw session rotate --profile agent --resume --password-stdin --json
+```
+
+## Session Revoke
+
+Revoke a non-active session on-chain, verify, then delete local file:
+
+```bash
+echo "my-password" | tw session revoke worker-1 --profile agent --password-stdin --json
+```
+
+Force revoke active session:
+
+```bash
+echo "my-password" | tw session revoke worker-2 --profile agent --force --password-stdin
+```
+
+Idempotent retry/cleanup when already revoked on-chain:
+
+```bash
+echo "my-password" | tw session revoke worker-2 --profile agent --resume --password-stdin --json
+```
+
+## Permissions List
+
+List all on-chain keys with summarized call/spend permissions:
+
+```bash
+tw permissions list --profile agent --json
+```
+
+## Permissions Show
+
+Show full permission rules for a key using positional `<key-ref>`:
+
+```bash
+tw permissions show agent-key --profile agent --json
+```
+
+Explicit selectors are also supported:
+
+```bash
+tw permissions show --key-hash 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --profile agent --json
+```
+
+## Permissions Grant
+
+Grant wildcard call permission:
+
+```bash
+echo "my-password" | tw permissions grant agent-key --type call --target any --selector any --profile agent --password-stdin --json
+```
+
+Grant spend permission for daily USDC limit:
+
+```bash
+echo "my-password" | tw permissions grant agent-key --type spend --token USDC --spend-limit 100 --period day --profile agent --password-stdin --json
+```
+
+## Permissions Revoke
+
+Revoke one rule by stable rule id:
+
+```bash
+echo "my-password" | tw permissions revoke agent-key --rule call:0x2222222222222222222222222222222222222222:0xa9059cbb --profile agent --password-stdin --json
+```
+
+Revoke all call/spend rules for a key:
+
+```bash
+echo "my-password" | tw permissions revoke agent-key --all --profile agent --password-stdin --json
+```
+
+## Password Automation
+
+Use `TW_PASSWORD` for non-interactive flows:
+
+```bash
+TW_PASSWORD="my-password" tw session list --profile agent --json
+```
+
+Stdin is supported for commands requiring keystore decryption/signing:
+
+```bash
+echo "my-password" | tw session rotate --profile agent --password-stdin --json
+```