From c70cd1f3b5eb0750129a85e97fdb383db1eb17ab Mon Sep 17 00:00:00 2001 From: roger-gan Date: Thu, 20 Aug 2026 16:02:29 +0800 Subject: [PATCH 1/7] feat: add wallet-cli skill --- wallet-cli/SKILL.md | 130 ++++++++++++++++++ wallet-cli/agents/openai.yaml | 6 + wallet-cli/references/commands.md | 111 +++++++++++++++ wallet-cli/references/machine-interface.md | 149 +++++++++++++++++++++ wallet-cli/references/safety.md | 105 +++++++++++++++ 5 files changed, 501 insertions(+) create mode 100644 wallet-cli/SKILL.md create mode 100644 wallet-cli/agents/openai.yaml create mode 100644 wallet-cli/references/commands.md create mode 100644 wallet-cli/references/machine-interface.md create mode 100644 wallet-cli/references/safety.md diff --git a/wallet-cli/SKILL.md b/wallet-cli/SKILL.md new file mode 100644 index 0000000..1a012f1 --- /dev/null +++ b/wallet-cli/SKILL.md @@ -0,0 +1,130 @@ +--- +name: wallet-cli +description: Operate the TypeScript TRON wallet CLI for accounts, transfers, staking, governance, contracts, signing, and chain queries. Use for TRON wallet operations with wallet-cli 4.12.0; do not use for other chains, SunSwap/DEX workflows, or the Java REPL. +version: 1.0.0 +dependencies: + - "@tron-walletcli/wallet-cli@4.12.0" +tags: + - tron + - wallet + - cli + - transfer + - staking + - governance +--- + +# TRON Wallet CLI + +Use the TypeScript, one-shot `wallet-cli` as the execution engine. Keep deterministic wallet, +signing, validation, and chain logic in the CLI; use this skill to select commands, enforce +authorization boundaries, and interpret results. + +This skill does not drive the repository's Java REPL and does not replace protocol-specific skills +such as SunSwap. Use a DEX skill for swaps or liquidity workflows and this skill for the wallet, +signing, resource, governance, and general TRON operations beneath them. + +## Verify the dependency + +Check once before the first wallet operation: + +```bash +wallet-cli --version +``` + +The required version is exactly `4.12.0`. + +- If the command is missing, explain that the exact package + `@tron-walletcli/wallet-cli@4.12.0` must be installed and obtain user approval before running + `npm install -g @tron-walletcli/wallet-cli@4.12.0`. +- If another version is installed, report the mismatch and obtain approval before upgrading or + downgrading it. Do not assume compatibility. +- Never install or change a global package without approval. + +## Mandatory invocation contract + +1. Use `-o json` for every operational command. Parse stdout as exactly one + `wallet-cli.result.v1` object. +2. Supply an explicit canonical network for chain operations: `tron:mainnet`, `tron:nile`, or + `tron:shasta`. Never silently choose mainnet. Use `tron:nile` when the user explicitly asks for + a test but does not distinguish between testnets. +3. Branch on the process exit code first: `0` success, `1` execution failure, `2` malformed call. + Then branch on stable fields such as `error.code`, `data.stage`, or `data.state`. Never parse + `error.message` text. +4. Treat all on-chain amounts as decimal strings, not JavaScript numbers or floating-point values. +5. Set `--timeout ` when the surrounding task has a tighter deadline than the CLI's 60-second + default. +6. Never infer that exit code `0` means a transaction confirmed. A submitted or reverted + transaction can still have a successful command envelope. + +Read [references/machine-interface.md](references/machine-interface.md) before implementing result +parsing, polling, pagination, retry logic, or non-interactive secret input. + +## Discover commands instead of guessing + +Prefer the CLI's generated schema over recalled flags: + +```bash +wallet-cli --json-schema +wallet-cli tx send --json-schema +wallet-cli permission update --json-schema +``` + +Use `wallet-cli --help` only when human-oriented semantics are needed. Do not invent a +flag, option combination, output field, or command that is absent from the 4.12.0 schema. + +Read [references/commands.md](references/commands.md) when choosing a command family or composing a +multi-step wallet workflow. + +## Secret handling + +- Never ask the user to paste a password, mnemonic, private key, or service credential into chat. +- Never place secrets in argv, environment variables, logs, command substitutions, or generated + documentation. +- Use only a CLI-supported `*-stdin` flag connected to an approved, non-logging secret source. + Only one `*-stdin` consumer may be used in a single invocation. +- Mnemonic/private-key import and `change-password` require hidden interactive TTY input. Ask the + user to perform those prompts; do not automate them through visible input. +- Do not read, summarize, or transmit keystores, backup files, configuration credentials, or other + wallet secret material. + +## Authorization and confirmation + +Read [references/safety.md](references/safety.md) before any operation that changes local wallet +state, signs data, broadcasts a transaction, or changes on-chain state. + +Apply these confirmed rules: + +- Read-only operations may run directly within the user's requested scope. +- On Nile or Shasta, an ordinary write may run when the user's request clearly authorizes that + exact operation and target. +- On mainnet, preview the exact operation and obtain explicit confirmation immediately before any + funds-moving or externally visible write. +- On every network, high-risk operations require explicit confirmation. `permission update` also + requires a successful `--dry-run` and review of the complete rendered permission structure. +- Never use authorization for one transaction as permission for another transaction, retry, batch, + recipient, amount, token, account, or network. + +## Transaction completion + +- Prefer `--wait` when the command supports it and the task can tolerate waiting. After it returns, + inspect `data.stage`; `failed` is an on-chain failure even when the process exits `0`. +- Otherwise retain the `txId` and poll `tx status` until `confirmed` or `failed`, with a finite + deadline. `pending` and `not_found` are non-terminal. +- GasFree transfers return a `traceId`; follow them with `gasfree trace`, not `tx status`. +- After a timeout or ambiguous submission, reconcile the transaction before retrying. Never resend + merely because confirmation was not observed. +- For a batch, stop on the first failure by default and track every submitted transaction + separately. + +## Report the outcome + +For reads, return the requested data with the network and account context when relevant. For writes, +report the operation, network, account, recipient or target, amount or parameters, and final state. +Include the `txId` or GasFree `traceId`; describe `submitted` as pending, never as completed. + +## Maintain the version pin + +When updating the CLI dependency, compare the new package's bundled `skills/wallet-cli/SKILL.md`, +`docs/machine-interface.md`, `docs/commands/index.md`, and generated `--json-schema` output. Re-test +the confirmation matrix, secret channels, exit codes, transaction stages, and warning codes before +bumping this skill's version. Do not widen the exact dependency pin without user approval. diff --git a/wallet-cli/agents/openai.yaml b/wallet-cli/agents/openai.yaml new file mode 100644 index 0000000..836b10e --- /dev/null +++ b/wallet-cli/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "TRON Wallet CLI" + short_description: "Operate TRON wallets safely with wallet-cli" + +policy: + allow_implicit_invocation: true diff --git a/wallet-cli/references/commands.md b/wallet-cli/references/commands.md new file mode 100644 index 0000000..c22a464 --- /dev/null +++ b/wallet-cli/references/commands.md @@ -0,0 +1,111 @@ +# Command Routing + +Use this reference to select a wallet-cli command family. It summarizes version 4.12.0; the CLI's +generated schema remains authoritative for exact flags and combinations. + +## Discover the live command contract + +```bash +wallet-cli --json-schema +wallet-cli --json-schema +wallet-cli --json-schema +``` + +Root and group schemas return command catalogs. A leaf schema describes its accepted inputs. Use +`--help` only when the schema does not communicate enough human meaning. + +Every operational example below must also include `-o json`. Chain operations must include an +explicit `--network tron:mainnet|tron:nile|tron:shasta`. + +## Local wallet and account lifecycle + +| Goal | Command family | Notes | +|---|---|---| +| Create an HD wallet | `create` | Hidden password prompt or supported stdin channel | +| Import an account | `import mnemonic|private-key|keystore|ledger|watch` | Mnemonic/private-key import is interactive-only | +| List/select accounts | `list`, `use`, `current` | `--account` can select without changing the active account | +| Derive or rename | `derive`, `rename` | Local wallet-state changes | +| Back up | `backup` | Writes secret material; high-risk confirmation required | +| Delete | `delete` | HD-root deletion can cascade; high-risk confirmation required | +| Change password | `change-password` | Interactive-only | +| Generate an unstored keypair | `address generate` | `--print-secret` exposes a private key to stdout | + +## Read-only chain operations + +| Goal | Command family | +|---|---| +| Account balance, details, history, portfolio | `account balance|info|history|portfolio` | +| Transaction state or receipt | `tx status|info` | +| Account permissions | `permission show` | +| Staking and delegation state | `stake info|delegated` | +| Votes and rewards | `vote list|status`, `reward balance` | +| Blocks and node state | `block`, `chain params|prices|node` | +| Token metadata and balances | `token info|balance|list` | +| Contract reads and metadata | `contract call|info` | +| Governance proposals | `proposal list|show` | +| TRC10 assets | `asset info|list` | +| Protocol exchange pairs | `exchange show|list` | +| GasFree state | `gasfree info|trace` | + +## Transfers and transaction lifecycle + +Use `tx send` for TRX, TRC20, or TRC10 transfers. It accepts exactly one amount representation and +at most one token selector: + +```bash +wallet-cli tx send --to T... --amount 1 --network tron:nile --dry-run -o json +``` + +- No selector means TRX. +- `--token` resolves an address-book symbol. +- `--contract` selects a TRC20 contract address. +- `--asset-id` selects a TRC10 id. +- `--amount` is a human-unit decimal string; `--raw-amount` is an unscaled integer string. +- `--dry-run` builds and estimates without signing or broadcasting. +- `--sign-only` emits signed transaction hex; `--build-only` emits unsigned hex. +- `--wait` polls after broadcast but can still return `data.stage: "submitted"` when its wait cap + expires. + +Use `tx sign` and `tx approvals` for file-based multi-signature artifacts. Use `tx multisig` for the +TronLink collaboration service. Broadcast only after signature threshold validation: + +```text +build unsigned → collect signatures → inspect approvals → dry-run broadcast → broadcast once +``` + +`tx broadcast` validates expiration and signature weight before submission. Its default success +still means submitted, not confirmed. + +## Resource, governance, and contract writes + +| Goal | Command family | +|---|---| +| Stake and delegate resources | `stake freeze|unfreeze|withdraw|cancel-unfreeze|delegate|undelegate` | +| Vote or claim rewards | `vote cast`, `reward withdraw` | +| Activate or name an account | `account activate`, `account set` | +| Contract write/deploy/governance | `contract send|deploy|clear-abi|set-origin-energy-limit|set-user-resource-percent|create2` | +| Replace permissions | `permission update` | +| GasFree transfer | `gasfree transfer` | +| Proposal governance | `proposal create|approve|delete` | +| Super-representative operation | `witness create|update|set-brokerage` | +| TRC10 lifecycle | `asset issue|update|participate|unfreeze` | +| Protocol exchange | `exchange create|inject|withdraw|trade` | + +Treat every command in this section as a write. Apply the network and confirmation matrix in +[safety.md](safety.md) before execution. + +## Local address books and configuration + +- `contact add|list|remove` manages recipient aliases accepted by `--to`. +- `token add|list|remove|info|balance` manages token metadata and queries token state. +- `config` changes CLI configuration, including service credentials. Never print or read credential + values into model context. +- `networks` lists canonical network ids. +- `encoding convert` converts or validates address and binary encodings locally. +- `message sign` and `typed-data sign` create externally usable signatures; treat them as visible + writes and confirm the exact payload/domain before signing. + +## Scope boundary + +This CLI manages wallets and generic TRON operations. Route SunSwap swaps, pool discovery, pricing, +and liquidity management to the SunSwap skill. Route non-TRON chains to their own wallet tools. diff --git a/wallet-cli/references/machine-interface.md b/wallet-cli/references/machine-interface.md new file mode 100644 index 0000000..a98f46f --- /dev/null +++ b/wallet-cli/references/machine-interface.md @@ -0,0 +1,149 @@ +# Machine Interface Contract + +Use this reference when parsing results, handling errors, polling transactions, paginating, or +providing secrets non-interactively. It summarizes the stable `wallet-cli.result.v1` contract in +wallet-cli 4.12.0. + +## Calling convention + +```bash +wallet-cli -o json [--network ] [--timeout ] [--account ] +``` + +JSON mode writes exactly one terminal result object to stdout. Diagnostics go to stderr. + +## Exit codes + +| Exit | Meaning | First response | +|---|---|---| +| `0` | The CLI completed the requested command | Inspect `success`, then command-specific state | +| `1` | Runtime, network, wallet, signing, or chain execution failure | Branch on `error.code`; reconcile ambiguous broadcasts | +| `2` | Malformed or invalid invocation | Correct flags/values using `--json-schema`; do not retry unchanged | + +The exit-code class is the hard contract. Error-code values are extensible, so tolerate unknown +codes within the same exit class. + +## Result envelope + +Success: + +```json +{ + "schema": "wallet-cli.result.v1", + "success": true, + "command": "account.balance", + "data": {}, + "meta": { "durationMs": 42, "warnings": [] }, + "chain": { "family": "tron", "network": "tron:nile", "chainId": "nile" } +} +``` + +Failure: + +```json +{ + "schema": "wallet-cli.result.v1", + "success": false, + "command": "tx.info", + "error": { "code": "rpc_error", "message": "human-readable only" }, + "meta": { "durationMs": 42, "warnings": [] }, + "chain": { "family": "tron", "network": "tron:nile", "chainId": "nile" } +} +``` + +- Require `schema == "wallet-cli.result.v1"`; stop on a different schema. +- `command` is the canonical operation id, not necessarily the literal words entered. +- `data` exists on success; `error` exists on failure. +- `chain` is present only for chain operations. +- `error.code` is machine-readable. `error.message` is unstable and must not be parsed. +- Big integers and on-chain quantities are decimal strings. Keep them as strings or arbitrary- + precision integers; never use floating point. + +## Warnings + +`meta.warnings` is always an array whose elements may be either strings or objects: + +```json +["plain notice", {"code":"owner_lockout_partial","message":"human-readable notice"}] +``` + +Normalize both forms for display. Branch only on object `code`, never warning message text. A +warning does not change `success`; high-risk warning codes can require stopping even on exit `0`. + +For `permission update`, stop on `owner_lockout` and require explicit review of +`owner_lockout_partial` or `active_can_update_permission` before proceeding. + +## Error decisions + +- Exit `2`, including `usage_error`, `missing_option`, `invalid_option`, and `invalid_value`: inspect + the leaf `--json-schema`, fix the request, then retry. +- `timeout`: increase the timeout only if still within the task deadline. If broadcasting may have + occurred, reconcile transaction state before retrying. +- `rpc_error`: verify network, endpoint, address, funds, resources, and permission. Do not retry + blindly. +- `auth_required` or `auth_failed`: use the approved secret channel or return control to the user; + never request the password in chat. +- `insufficient_balance` or `insufficient_token_balance`: stop and report the shortfall. +- `internal_error`: stop and report; do not loop. +- If `error.details.matches` exists, present the structured candidates and ask the user to select + rather than parsing `error.message`. + +## Pagination + +Commands that accept `--limit` and `--offset` report: + +```json +{"offset":0,"limit":50,"total":null} +``` + +under `meta.pagination`. `total: null` means the endpoint exposes no total. Page until a short page +is returned; do not treat null as zero and do not fetch unbounded pages without need. + +## Transaction state + +Broadcasting commands normally return: + +```json +{"kind":"send","stage":"submitted","txId":"..."} +``` + +`submitted` is pending, not completed. + +- With `--wait`, inspect `data.stage`: `confirmed`, `failed`, or still `submitted` after the wait + cap. A mined revert can return exit `0`, `success: true`, and `stage: "failed"`. +- Without `--wait`, poll `tx status` using a finite deadline: + +| `data.state` | Terminal | Action | +|---|---|---| +| `confirmed` | yes | Report completion with txid/block | +| `failed` | yes | Report the on-chain failure; do not retry automatically | +| `pending` | no | Continue within the deadline | +| `not_found` | no | Continue within the deadline; verify network before concluding | + +GasFree is different: `gasfree transfer` returns `traceId`. Poll `gasfree trace` through provider +states until `SUCCEED` or `FAILED`; do not pass a trace id to `tx status`. + +## Duplicate prevention + +- One authorized request produces at most one transaction unless the user explicitly authorizes a + batch. +- Persist or retain the `txId`/`traceId` immediately after submission. +- After timeout, lost output, `pending`, or `not_found`, reconcile within a bounded period before + considering another broadcast. +- Stop on first batch failure by default and report the per-item states. + +## Secret channels + +Secrets are never valid in argv or environment variables. + +- Use CLI-supported flags such as `--password-stdin`, `--tx-stdin`, or `--message-stdin` only with + an approved, non-logging stdin source. +- Only one `*-stdin` option may consume stdin in a single process. +- Mnemonic/private-key import and `change-password` require a hidden interactive TTY; return those + steps to the user. +- Never capture secret-producing output such as `address generate --print-secret` in model context. + +## Version boundary + +This contract is pinned to wallet-cli `4.12.0`. If the installed version differs, stop and obtain +approval before changing it. Do not silently apply this reference to another version. diff --git a/wallet-cli/references/safety.md b/wallet-cli/references/safety.md new file mode 100644 index 0000000..cf673dc --- /dev/null +++ b/wallet-cli/references/safety.md @@ -0,0 +1,105 @@ +# Safety and Authorization + +Read this reference before any local wallet mutation, signature, broadcast, or on-chain write. + +## Networks + +| Network | Meaning | Policy | +|---|---|---| +| `tron:mainnet` | Production; real funds and persistent public state | Preview and explicit confirmation before funds-moving or externally visible writes | +| `tron:nile` | Primary testnet | Clearly authorized ordinary writes may proceed without a second confirmation | +| `tron:shasta` | Alternate testnet | Clearly authorized ordinary writes may proceed without a second confirmation | + +Always pass the canonical network explicitly for chain operations. Never infer mainnet from an +address because TRON addresses are identical across networks. + +## Confirmation matrix + +| Operation | Testnet | Mainnet | +|---|---|---| +| Read-only query | Execute within scope | Execute within scope | +| Ordinary wallet or chain write | User's clear request authorizes the exact operation | Preview, then obtain explicit confirmation immediately before execution | +| Funds transfer, broadcast, contract write, staking, voting, governance, exchange, or GasFree transfer | User's clear request authorizes the exact operation | Preview, then obtain explicit confirmation immediately before execution | +| High-risk local or permission operation | Always preview where possible and confirm | Always preview where possible and confirm | + +A confirmation is scoped to the displayed network, account, target, command, amount, asset, +parameters, and one execution. Any change requires a new confirmation. + +## High-risk operations on every network + +### `permission update` + +This replaces the entire permission structure. A wrong owner group can lock the account permanently. + +1. Read the current structure with `permission show`. +2. Generate or review the complete replacement file. +3. Run `permission update --dry-run -o json`. +4. Inspect the resulting owner/witness/active groups, thresholds, key weights, and operation bitmap. +5. Stop on `owner_lockout`; explicitly surface `owner_lockout_partial` and + `active_can_update_permission` warnings. +6. Obtain explicit confirmation of the rendered replacement. +7. Execute once, preferably with `--wait`, and inspect `data.stage` plus warnings. + +Never reconstruct a permission bitmap from memory when the CLI can export or decode it. + +### `delete` + +Confirm the exact account id/label and cascade impact. Deleting an HD seed root can remove its +derived accounts. Do not infer that a usable backup exists unless the user verifies it. + +### `backup` + +Confirm the exact account, export format, and destination path. The output is secret material. +Never read the created file, overwrite an existing path, or include its contents in model context. + +### `address generate --print-secret` + +The option writes a private key to stdout. Do not run it in an agent session. Prefer the default +file output and tell the user where it was written without reading the file. + +### Signing arbitrary content + +For `message sign`, `typed-data sign`, transaction signing, and contract writes, show the exact +human-meaningful payload, domain, network, account, permission id, and destination before signing. +Treat opaque or untrusted payloads as high risk. Never sign a challenge whose purpose is unclear. + +### One-shot account operations + +`account activate` charges the active payer. On-chain account name and id settings are effectively +one-time. Confirm payer, target, name/id, network, and irreversibility before execution. + +## Preview contents + +Before a mainnet confirmation, show all fields available for the operation: + +- canonical network; +- source account label/id and public address; +- recipient, contract, proposal, witness, exchange, permission, or other target; +- human amount plus raw base-unit amount when available; +- token symbol and verified contract/asset id; +- fee limit, resource, duration, lock, slippage/min-return, permission id, and other material flags; +- whether the command will build, sign, submit, wait, write a file, or expose a secret; +- dry-run estimates and warnings. + +Do not ask for confirmation using only an opaque command string when the values can be explained. + +## Secret and file safety + +- Never request or display passwords, mnemonics, private keys, signing material, or service + credentials. +- Never read wallet stores, keystores, generated private-key files, backup outputs, or credential + fields into model context. +- Do not pass secrets through argv, environment variables, shell history, logs, or temporary files. +- Do not overwrite output files. Respect `output_exists` and ask the user for a new destination. +- Public addresses, txids, block numbers, balances, token metadata, and transaction receipts are + safe to report unless the user imposes a stricter privacy boundary. + +## Retry and stopping rules + +- Never retry a successful submission. +- A timeout during signing or broadcasting is ambiguous. Check `tx status`, transaction history, + or the relevant provider trace before any retry. +- `pending` and `not_found` are not permission to resend. +- Do not continue a batch after failure unless the user explicitly requested best-effort behavior. +- Stop when the requested operation reaches a terminal state, the task deadline expires, or user + input is required. Report unresolved txids/trace ids for later reconciliation. From cddadf075f6b0637598f46b251789120b22ae9a1 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Thu, 20 Aug 2026 16:20:00 +0800 Subject: [PATCH 2/7] feat: add optional wallet-cli installer --- README.md | 23 +++- wallet-cli/README.md | 52 ++++++++ wallet-cli/install.sh | 276 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 350 insertions(+), 1 deletion(-) create mode 100644 wallet-cli/README.md create mode 100755 wallet-cli/install.sh diff --git a/README.md b/README.md index b641101..091a7d9 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,10 @@ A curated collection of practical, DeFi-focused utility skills developed by the - [What are BANK OF AI Skills?](#what-are-bank-of-ai-skills) - [Installation](#installation) + - [Optional wallet-cli installer](#optional-wallet-cli-installer) - [Agent Wallet (Required for Signing Skills)](#agent-wallet-required-for-signing-skills) - [Available Skills](#available-skills) + - [Wallet & TRON](#wallet--tron) - [DeFi & DEX](#defi--dex) - [Payments & x402](#payments--x402) - [AI & Account Recharge](#ai--account-recharge) @@ -43,12 +45,26 @@ BANK OF AI Skills are reusable, task-oriented capabilities that teach AI agents ## Installation -Use the unified installer and follow the `npx` prompts to select the skills you want and the agentic platform you use. The installer will complete the setup automatically. +Use the standard installer and follow the `npx` prompts to select the skills you want and the agentic platform you use. This installs the selected Skill definitions; external CLI dependencies are never installed globally without explicit user approval. ```bash npx skills add https://github.com/BofAI/skills.git ``` +### Optional wallet-cli installer + +The standard installer above remains the recommended path. To install only the `wallet-cli` Skill and optionally install its pinned CLI dependency in one flow, use: + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh +``` + +The script displays the exact npm package and version, then asks for confirmation before running a global `npm install`. Declining the prompt installs the Skill only. Preview all actions without changing the system with: + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -s -- --dry-run +``` + ### Agent Wallet (Required for Signing Skills) Some skills require wallet signature operations and are built on Agent Wallet. Before using those skills, follow the [Agent Wallet Quick Start](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start) to configure your environment. @@ -57,6 +73,10 @@ Some skills require wallet signature operations and are built on Agent Wallet. B ## Available Skills +### Wallet & TRON + +- [**wallet-cli**](./wallet-cli) - Safe, machine-readable TRON wallet operations through `@tron-walletcli/wallet-cli@4.12.0`, including accounts, transfers, staking, governance, contracts, signing, and chain queries. See [README](./wallet-cli/README.md). + ### DeFi & DEX - [**sunswap**](./sunswap) - SunSwap DEX integration for TRON via `sun-cli`. Supports price quotes, token swaps, liquidity and pool operations. See [README](./sunswap/README.md). @@ -100,6 +120,7 @@ Each current skill now has its own README for quick discovery: - [tronscan-skill/README.md](./tronscan-skill/README.md) - [trx-staking-skill/README.md](./trx-staking-skill/README.md) - [usdd-skill/README.md](./usdd-skill/README.md) +- [wallet-cli/README.md](./wallet-cli/README.md) - [x402-payment/README.md](./x402-payment/README.md) --- diff --git a/wallet-cli/README.md b/wallet-cli/README.md new file mode 100644 index 0000000..7d3e587 --- /dev/null +++ b/wallet-cli/README.md @@ -0,0 +1,52 @@ +# TRON Wallet CLI Skill + +Agent instructions for operating the TypeScript `wallet-cli` safely through its machine-readable +interface. The Skill covers TRON accounts, transfers, staking, governance, contracts, signing, and +chain queries and is pinned to `@tron-walletcli/wallet-cli@4.12.0`. + +## Installation + +The recommended installation path is the repository's standard interactive installer: + +```bash +npx skills add https://github.com/BofAI/skills.git +``` + +Select `wallet-cli` and the target agent platform when prompted. This installs the Skill but does +not silently modify global npm packages. + +For an optional wallet-cli-specific installation flow: + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh +``` + +The script installs the Skill and asks for explicit confirmation before running: + +```bash +npm install --global --no-fund --no-audit @tron-walletcli/wallet-cli@4.12.0 +``` + +Declining the prompt or passing `--skip-cli-install` installs only the Skill. Use `--dry-run` to +preview the operation: + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -s -- --dry-run +``` + +## Contents + +- [SKILL.md](SKILL.md) — operational rules and version boundary +- [install.sh](install.sh) — optional confirmed installation flow +- [references/commands.md](references/commands.md) — command-family routing +- [references/machine-interface.md](references/machine-interface.md) — JSON, exit-code, and transaction-state contract +- [references/safety.md](references/safety.md) — authorization, confirmation, secret, and retry rules + +## Requirements + +- Node.js 20 or newer when installing the npm CLI +- Git for the optional installer +- Explicit network selection for chain operations + +The Skill never authorizes an installer or Agent to collect wallet passwords, mnemonics, or private +keys. diff --git a/wallet-cli/install.sh b/wallet-cli/install.sh new file mode 100755 index 0000000..e07e07e --- /dev/null +++ b/wallet-cli/install.sh @@ -0,0 +1,276 @@ +#!/bin/sh +set -eu + +SKILL_NAME="wallet-cli" +CLI_PACKAGE="@tron-walletcli/wallet-cli" +CLI_VERSION="4.12.0" + +TAG="${WALLET_CLI_SKILL_TAG:-main}" +REPO="${WALLET_CLI_SKILL_REPO:-https://github.com/BofAI/skills.git}" +CLIENT="${WALLET_CLI_SKILL_CLIENT:-auto}" +SKILLS_DIR_OVERRIDE="${WALLET_CLI_SKILLS_DIR:-}" +SKIP_CLI_INSTALL="${WALLET_CLI_SKIP_CLI_INSTALL:-0}" +DRY_RUN=0 +WORKDIR="" + +info() { + printf '==> %s\n' "$1" +} + +fail() { + printf 'Error: %s\n' "$1" >&2 + exit 1 +} + +command_exists() { + command -v "$1" >/dev/null 2>&1 +} + +truthy() { + case "${1:-}" in + 1|true|yes) return 0 ;; + *) return 1 ;; + esac +} + +usage() { + cat <] [--skip-cli-install] [--dry-run] + +Install the ${SKILL_NAME} Skill. Unless --skip-cli-install is used, the script +asks for confirmation before installing ${CLI_PACKAGE}@${CLI_VERSION} globally. + +Options: + --client Target client. Default: auto. + --skills-dir Override the target Skills directory. + --skip-cli-install Install the Skill without offering to install the npm CLI. + --dry-run Preview actions without changing files or packages. + -h, --help Show this help. +EOF +} + +while [ "$#" -gt 0 ]; do + case "$1" in + --client) + [ "$#" -ge 2 ] || fail "--client requires a value" + CLIENT="$2" + shift 2 + ;; + --client=*) + CLIENT="${1#--client=}" + shift + ;; + --skills-dir) + [ "$#" -ge 2 ] || fail "--skills-dir requires a value" + SKILLS_DIR_OVERRIDE="$2" + shift 2 + ;; + --skills-dir=*) + SKILLS_DIR_OVERRIDE="${1#--skills-dir=}" + shift + ;; + --skip-cli-install) + SKIP_CLI_INSTALL=1 + shift + ;; + --dry-run) + DRY_RUN=1 + shift + ;; + -h|--help) + usage + exit 0 + ;; + *) + fail "Unknown argument: $1" + ;; + esac +done + +case "$CLIENT" in + auto|codex|claude|all) ;; + *) fail "--client must be auto, codex, claude, or all" ;; +esac + +command_exists git || fail "git is required to install ${SKILL_NAME}." + +check_node_and_npm() { + command_exists node || fail "Node.js 20+ is required to install ${CLI_PACKAGE}." + node_major="$(node -e 'process.stdout.write(String(process.versions.node.split(".")[0]))' 2>/dev/null || printf '0')" + [ "$node_major" -ge 20 ] 2>/dev/null || fail "Node.js 20+ is required; detected $(node --version 2>/dev/null || printf 'unknown')." + command_exists npm || fail "npm is required to install ${CLI_PACKAGE}." +} + +installed_cli_version() { + if ! command_exists wallet-cli; then + return 1 + fi + wallet-cli --version 2>/dev/null +} + +confirm_cli_install() { + if [ ! -r /dev/tty ]; then + info "No interactive terminal is available; skipping global npm installation." + return 1 + fi + + printf '\nInstall %s@%s globally with npm? [y/N] ' "$CLI_PACKAGE" "$CLI_VERSION" >/dev/tty + answer="" + IFS= read -r answer Date: Thu, 20 Aug 2026 16:25:48 +0800 Subject: [PATCH 3/7] docs: require password input via stdin --- wallet-cli/references/safety.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/wallet-cli/references/safety.md b/wallet-cli/references/safety.md index cf673dc..0b353a6 100644 --- a/wallet-cli/references/safety.md +++ b/wallet-cli/references/safety.md @@ -83,6 +83,30 @@ Before a mainnet confirmation, show all fields available for the operation: Do not ask for confirmation using only an opaque command string when the values can be explained. +## Password input: `--password-stdin` only + +For agent-driven or other non-interactive execution, `--password-stdin` is the only permitted way +to pass the wallet master password. The flag reads one password from standard input; never invent +or use a `--password` argument, literal password, environment variable, command substitution, +temporary file, or visible chat message. + +Pipe the password directly from an approved, non-logging password manager. For example, with the +1Password CLI already configured by the user: + +```bash +op read "op://Private/wallet-cli/password" | + wallet-cli create --label main --password-stdin -o json +``` + +Replace only the password-manager item locator; never replace it with the password itself. If no +approved secret source is available, stop and return control to the user instead of using +`echo`, placing the password in an environment variable, or asking for it in chat. + +Standard input can have only one consumer. Do not combine `--password-stdin` with `--tx-stdin` or +`--message-stdin` in the same invocation; provide the non-secret payload through a supported file +or inline option, or split the workflow. Mnemonic/private-key imports and `change-password` remain +hidden interactive TTY operations and do not accept `--password-stdin`. + ## Secret and file safety - Never request or display passwords, mnemonics, private keys, signing material, or service From 15f0f96c005f64ba468c2378b01e111c54f864a8 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Thu, 20 Aug 2026 16:37:32 +0800 Subject: [PATCH 4/7] docs: make wallet administration human-only --- wallet-cli/SKILL.md | 15 +++++++++++++-- wallet-cli/references/commands.md | 8 ++++---- wallet-cli/references/safety.md | 31 +++++++++++++++++++------------ 3 files changed, 36 insertions(+), 18 deletions(-) diff --git a/wallet-cli/SKILL.md b/wallet-cli/SKILL.md index 1a012f1..b180413 100644 --- a/wallet-cli/SKILL.md +++ b/wallet-cli/SKILL.md @@ -82,11 +82,21 @@ multi-step wallet workflow. documentation. - Use only a CLI-supported `*-stdin` flag connected to an approved, non-logging secret source. Only one `*-stdin` consumer may be used in a single invocation. -- Mnemonic/private-key import and `change-password` require hidden interactive TTY input. Ask the - user to perform those prompts; do not automate them through visible input. - Do not read, summarize, or transmit keystores, backup files, configuration credentials, or other wallet secret material. +## Human-only wallet administration + +Never invoke `wallet-cli import`, `wallet-cli backup`, `wallet-cli delete`, or +`wallet-cli change-password`, including any `wallet-cli import` subcommand. These root wallet +administration commands are reserved for a human operating wallet-cli locally, even when the user +asks the agent to run them, supplies confirmation, or provides a secret source. + +Explain the consequences and required precautions, then return control to the user. Do not automate +their prompts, pipe input to them, read their output files, or treat confirmation as authorization +to execute them. After the user reports completion, continue only with non-secret public results +such as an account id, label, or address. + ## Authorization and confirmation Read [references/safety.md](references/safety.md) before any operation that changes local wallet @@ -101,6 +111,7 @@ Apply these confirmed rules: funds-moving or externally visible write. - On every network, high-risk operations require explicit confirmation. `permission update` also requires a successful `--dry-run` and review of the complete rendered permission structure. +- Confirmation never authorizes a human-only command listed above. - Never use authorization for one transaction as permission for another transaction, retry, batch, recipient, amount, token, account, or network. diff --git a/wallet-cli/references/commands.md b/wallet-cli/references/commands.md index c22a464..95a0f50 100644 --- a/wallet-cli/references/commands.md +++ b/wallet-cli/references/commands.md @@ -22,12 +22,12 @@ explicit `--network tron:mainnet|tron:nile|tron:shasta`. | Goal | Command family | Notes | |---|---|---| | Create an HD wallet | `create` | Hidden password prompt or supported stdin channel | -| Import an account | `import mnemonic|private-key|keystore|ledger|watch` | Mnemonic/private-key import is interactive-only | +| Import an account | `import mnemonic|private-key|keystore|ledger|watch` | Human-only; the Agent must not invoke any import subcommand | | List/select accounts | `list`, `use`, `current` | `--account` can select without changing the active account | | Derive or rename | `derive`, `rename` | Local wallet-state changes | -| Back up | `backup` | Writes secret material; high-risk confirmation required | -| Delete | `delete` | HD-root deletion can cascade; high-risk confirmation required | -| Change password | `change-password` | Interactive-only | +| Back up | `backup` | Human-only; writes secret recovery material | +| Delete | `delete` | Human-only; HD-root deletion can cascade | +| Change password | `change-password` | Human-only; hidden interactive TTY operation | | Generate an unstored keypair | `address generate` | `--print-secret` exposes a private key to stdout | ## Read-only chain operations diff --git a/wallet-cli/references/safety.md b/wallet-cli/references/safety.md index 0b353a6..c951642 100644 --- a/wallet-cli/references/safety.md +++ b/wallet-cli/references/safety.md @@ -25,6 +25,22 @@ address because TRON addresses are identical across networks. A confirmation is scoped to the displayed network, account, target, command, amount, asset, parameters, and one execution. Any change requires a new confirmation. +## Human-only wallet administration + +The Agent must never invoke `wallet-cli import`, `wallet-cli backup`, `wallet-cli delete`, or +`wallet-cli change-password`, including any `wallet-cli import` subcommand. This prohibition applies +on every network and cannot be overridden by user confirmation, a test environment, an approved +password source, or the CLI's technical ability to run non-interactively. + +- `import` introduces an external account or key source into the wallet store. +- `backup` creates secret recovery material outside the wallet store. +- `delete` can remove an HD seed root and all derived accounts. +- `change-password` handles both the current and replacement master passwords. + +Explain the operation and its consequences, then return control to the user to complete it locally. +Do not automate prompts, provide secrets, read generated files, or inspect secret-bearing output. +Afterward, accept only non-secret public results such as an account id, label, or address. + ## High-risk operations on every network ### `permission update` @@ -42,16 +58,6 @@ This replaces the entire permission structure. A wrong owner group can lock the Never reconstruct a permission bitmap from memory when the CLI can export or decode it. -### `delete` - -Confirm the exact account id/label and cascade impact. Deleting an HD seed root can remove its -derived accounts. Do not infer that a usable backup exists unless the user verifies it. - -### `backup` - -Confirm the exact account, export format, and destination path. The output is secret material. -Never read the created file, overwrite an existing path, or include its contents in model context. - ### `address generate --print-secret` The option writes a private key to stdout. Do not run it in an agent session. Prefer the default @@ -104,8 +110,9 @@ approved secret source is available, stop and return control to the user instead Standard input can have only one consumer. Do not combine `--password-stdin` with `--tx-stdin` or `--message-stdin` in the same invocation; provide the non-secret payload through a supported file -or inline option, or split the workflow. Mnemonic/private-key imports and `change-password` remain -hidden interactive TTY operations and do not accept `--password-stdin`. +or inline option, or split the workflow. The human-only command policy above remains absolute even +where wallet-cli technically supports `--password-stdin`; `change-password` and secret-bearing +imports remain hidden interactive TTY operations. ## Secret and file safety From 4f27010948073a92689350b4c7a4ed805439a6a0 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Thu, 20 Aug 2026 21:34:56 +0800 Subject: [PATCH 5/7] docs: refine wallet-cli agent guidance --- wallet-cli/SKILL.md | 10 ++++++++-- wallet-cli/references/machine-interface.md | 7 +++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/wallet-cli/SKILL.md b/wallet-cli/SKILL.md index b180413..0325efa 100644 --- a/wallet-cli/SKILL.md +++ b/wallet-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: wallet-cli -description: Operate the TypeScript TRON wallet CLI for accounts, transfers, staking, governance, contracts, signing, and chain queries. Use for TRON wallet operations with wallet-cli 4.12.0; do not use for other chains, SunSwap/DEX workflows, or the Java REPL. +description: Operate the TypeScript TRON wallet CLI for accounts, transfers, staking, governance, contracts, signing, chain queries, and password input with wallet-cli 4.12.0. Refuse wallet passwords in argv and require the supported stdin channel. For Java REPL requests, refuse that entry and offer the TypeScript one-shot CLI; route other chains and SunSwap/DEX workflows elsewhere. version: 1.0.0 dependencies: - "@tron-walletcli/wallet-cli@4.12.0" @@ -21,7 +21,10 @@ authorization boundaries, and interpret results. This skill does not drive the repository's Java REPL and does not replace protocol-specific skills such as SunSwap. Use a DEX skill for swaps or liquidity workflows and this skill for the wallet, -signing, resource, governance, and general TRON operations beneath them. +signing, resource, governance, and general TRON operations beneath them. If the user requests the +Java REPL, do not execute it or offer to switch to it; state that this skill supports only the +TypeScript one-shot CLI and, when applicable, offer to express the intended operation through that +interface. ## Verify the dependency @@ -77,6 +80,9 @@ multi-step wallet workflow. ## Secret handling +- Reject any request to put a wallet password in `--password` or another argv option. For + agent-driven execution, explain that wallet-cli passwords may be supplied only through + `--password-stdin` connected directly to an approved, non-logging secret source. - Never ask the user to paste a password, mnemonic, private key, or service credential into chat. - Never place secrets in argv, environment variables, logs, command substitutions, or generated documentation. diff --git a/wallet-cli/references/machine-interface.md b/wallet-cli/references/machine-interface.md index a98f46f..e5ddf46 100644 --- a/wallet-cli/references/machine-interface.md +++ b/wallet-cli/references/machine-interface.md @@ -56,8 +56,11 @@ Failure: - `data` exists on success; `error` exists on failure. - `chain` is present only for chain operations. - `error.code` is machine-readable. `error.message` is unstable and must not be parsed. -- Big integers and on-chain quantities are decimal strings. Keep them as strings or arbitrary- - precision integers; never use floating point. +- `bigint` values and on-chain amounts are decimal strings. Keep those fields as strings or + arbitrary-precision integers; never use floating point for them. +- Other counters and configuration values follow the command-specific documentation and schema and + may be JSON numbers. For example, `chain params.data.value` is a number in wallet-cli 4.12.0; do + not coerce a field based only on it coming from the chain. ## Warnings From c3a36e66cfdeb2bd24e5ab9f3cacbc82022452d3 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Fri, 21 Aug 2026 07:33:16 +0800 Subject: [PATCH 6/7] fix(wallet-cli): clarify interface and installer requirements --- wallet-cli/README.md | 6 +++++- wallet-cli/SKILL.md | 4 +++- wallet-cli/install.sh | 20 ++++++++++++++++++++ 3 files changed, 28 insertions(+), 2 deletions(-) diff --git a/wallet-cli/README.md b/wallet-cli/README.md index 7d3e587..c7ae74e 100644 --- a/wallet-cli/README.md +++ b/wallet-cli/README.md @@ -21,6 +21,10 @@ For an optional wallet-cli-specific installation flow: curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh ``` +The optional script requires a POSIX shell and standard utilities such as `mktemp`, `cp`, `mv`, and +`mkdir`. On Windows, run it only from Git Bash or WSL with those tools available on `PATH`; from +native PowerShell, use the standard `npx skills add` installation above. + The script installs the Skill and asks for explicit confirmation before running: ```bash @@ -45,7 +49,7 @@ curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/instal ## Requirements - Node.js 20 or newer when installing the npm CLI -- Git for the optional installer +- Git, a POSIX shell, and standard POSIX utilities for the optional installer - Explicit network selection for chain operations The Skill never authorizes an installer or Agent to collect wallet passwords, mnemonics, or private diff --git a/wallet-cli/SKILL.md b/wallet-cli/SKILL.md index 0325efa..c357a17 100644 --- a/wallet-cli/SKILL.md +++ b/wallet-cli/SKILL.md @@ -53,7 +53,9 @@ The required version is exactly `4.12.0`. 3. Branch on the process exit code first: `0` success, `1` execution failure, `2` malformed call. Then branch on stable fields such as `error.code`, `data.stage`, or `data.state`. Never parse `error.message` text. -4. Treat all on-chain amounts as decimal strings, not JavaScript numbers or floating-point values. +4. Treat `bigint` values and command-defined on-chain amount fields as decimal strings. Preserve + every field according to the leaf schema; other counters and configuration values may be JSON + numbers. Never use floating point for string amounts. 5. Set `--timeout ` when the surrounding task has a tighter deadline than the CLI's 60-second default. 6. Never infer that exit code `0` means a transaction confirmed. A submitted or reverted diff --git a/wallet-cli/install.sh b/wallet-cli/install.sh index e07e07e..c39b4f8 100755 --- a/wallet-cli/install.sh +++ b/wallet-cli/install.sh @@ -26,6 +26,23 @@ command_exists() { command -v "$1" >/dev/null 2>&1 } +require_posix_tools() { + missing="" + for tool in mktemp mkdir cp mv rm date dirname; do + if ! command_exists "$tool"; then + missing="${missing}${missing:+, }${tool}" + fi + done + if [ "$CLIENT" = "auto" ]; then + for tool in env grep; do + if ! command_exists "$tool"; then + missing="${missing}${missing:+, }${tool}" + fi + done + fi + [ -z "$missing" ] || fail "Required POSIX tools are missing from PATH: ${missing}. On Windows, use the standard 'npx skills add' installation or run this script from Git Bash/WSL with a complete POSIX PATH." +} + truthy() { case "${1:-}" in 1|true|yes) return 0 ;; @@ -93,6 +110,9 @@ case "$CLIENT" in esac command_exists git || fail "git is required to install ${SKILL_NAME}." +if [ "$DRY_RUN" != "1" ]; then + require_posix_tools +fi check_node_and_npm() { command_exists node || fail "Node.js 20+ is required to install ${CLI_PACKAGE}." From 84ed6d6c16a854f6ed354ceb1c2e92dbe2478d22 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Fri, 21 Aug 2026 14:53:39 +0800 Subject: [PATCH 7/7] feat(wallet-cli): streamline skill installation --- README.md | 17 +---- wallet-cli/README.md | 39 ++++++---- wallet-cli/install.sh | 162 ++++++++++++++++++++++++++++++------------ 3 files changed, 143 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 091a7d9..2eaea88 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,6 @@ A curated collection of practical, DeFi-focused utility skills developed by the - [What are BANK OF AI Skills?](#what-are-bank-of-ai-skills) - [Installation](#installation) - - [Optional wallet-cli installer](#optional-wallet-cli-installer) - [Agent Wallet (Required for Signing Skills)](#agent-wallet-required-for-signing-skills) - [Available Skills](#available-skills) - [Wallet & TRON](#wallet--tron) @@ -45,26 +44,12 @@ BANK OF AI Skills are reusable, task-oriented capabilities that teach AI agents ## Installation -Use the standard installer and follow the `npx` prompts to select the skills you want and the agentic platform you use. This installs the selected Skill definitions; external CLI dependencies are never installed globally without explicit user approval. +Use the standard installer and follow the `npx` prompts to select the skills you want and the agentic platform you use. This installs the selected Skill definitions but does not install their external CLI dependencies. ```bash npx skills add https://github.com/BofAI/skills.git ``` -### Optional wallet-cli installer - -The standard installer above remains the recommended path. To install only the `wallet-cli` Skill and optionally install its pinned CLI dependency in one flow, use: - -```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -``` - -The script displays the exact npm package and version, then asks for confirmation before running a global `npm install`. Declining the prompt installs the Skill only. Preview all actions without changing the system with: - -```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -s -- --dry-run -``` - ### Agent Wallet (Required for Signing Skills) Some skills require wallet signature operations and are built on Agent Wallet. Before using those skills, follow the [Agent Wallet Quick Start](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start) to configure your environment. diff --git a/wallet-cli/README.md b/wallet-cli/README.md index c7ae74e..7291f2c 100644 --- a/wallet-cli/README.md +++ b/wallet-cli/README.md @@ -6,42 +6,51 @@ chain queries and is pinned to `@tron-walletcli/wallet-cli@4.12.0`. ## Installation -The recommended installation path is the repository's standard interactive installer: +Choose either method below. Both install Skill version `1.0.0` and use +`@tron-walletcli/wallet-cli@4.12.0`. + +### Method 1: Install the CLI, then the Skill + +Install the pinned npm CLI first, then install the Skill through the standard Skills CLI: ```bash -npx skills add https://github.com/BofAI/skills.git +npm install --global --no-fund --no-audit @tron-walletcli/wallet-cli@4.12.0 +npx skills add BofAI/skills --skill wallet-cli --global --yes ``` -Select `wallet-cli` and the target agent platform when prompted. This installs the Skill but does -not silently modify global npm packages. +The `npx skills` command installs only the Skill; it does not install or update the `wallet-cli` +npm package. + +### Method 2: Install both with one script -For an optional wallet-cli-specific installation flow: +On macOS, Linux, Git Bash, or WSL, run the repository installer: ```bash curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh ``` -The optional script requires a POSIX shell and standard utilities such as `mktemp`, `cp`, `mv`, and -`mkdir`. On Windows, run it only from Git Bash or WSL with those tools available on `PATH`; from -native PowerShell, use the standard `npx skills add` installation above. +The script installs or verifies the pinned CLI and installs the Skill without prompting by default. +It requires a POSIX shell and standard utilities such as `mktemp`, `cp`, `mv`, and `mkdir`. -The script installs the Skill and asks for explicit confirmation before running: +Use `--ask` to show the complete plan and require one confirmation, `--skill-only` to leave npm +packages unchanged, or `--dry-run` to preview the operation: ```bash -npm install --global --no-fund --no-audit @tron-walletcli/wallet-cli@4.12.0 +curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -s -- --ask +curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -s -- --skill-only +curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -s -- --dry-run ``` -Declining the prompt or passing `--skip-cli-install` installs only the Skill. Use `--dry-run` to -preview the operation: +After either method, verify the CLI version: ```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/install.sh | sh -s -- --dry-run +wallet-cli --version ``` ## Contents - [SKILL.md](SKILL.md) — operational rules and version boundary -- [install.sh](install.sh) — optional confirmed installation flow +- [install.sh](install.sh) — one-command Skill and pinned CLI setup - [references/commands.md](references/commands.md) — command-family routing - [references/machine-interface.md](references/machine-interface.md) — JSON, exit-code, and transaction-state contract - [references/safety.md](references/safety.md) — authorization, confirmation, secret, and retry rules @@ -49,7 +58,7 @@ curl -fsSL https://raw.githubusercontent.com/BofAI/skills/main/wallet-cli/instal ## Requirements - Node.js 20 or newer when installing the npm CLI -- Git, a POSIX shell, and standard POSIX utilities for the optional installer +- Git, a POSIX shell, and standard POSIX utilities for the one-command installer - Explicit network selection for chain operations The Skill never authorizes an installer or Agent to collect wallet passwords, mnemonics, or private diff --git a/wallet-cli/install.sh b/wallet-cli/install.sh index c39b4f8..4afa40c 100755 --- a/wallet-cli/install.sh +++ b/wallet-cli/install.sh @@ -10,8 +10,12 @@ REPO="${WALLET_CLI_SKILL_REPO:-https://github.com/BofAI/skills.git}" CLIENT="${WALLET_CLI_SKILL_CLIENT:-auto}" SKILLS_DIR_OVERRIDE="${WALLET_CLI_SKILLS_DIR:-}" SKIP_CLI_INSTALL="${WALLET_CLI_SKIP_CLI_INSTALL:-0}" +ASSUME_YES="${WALLET_CLI_INSTALL_YES:-1}" DRY_RUN=0 WORKDIR="" +SOURCE_DIR="" +CLI_ACTION="skip" +CURRENT_CLI_VERSION="" info() { printf '==> %s\n' "$1" @@ -52,15 +56,20 @@ truthy() { usage() { cat <] [--skip-cli-install] [--dry-run] +Usage: install.sh [--client auto|codex|claude|all] [--skills-dir ] [--tag ] [--yes|--ask] [--skill-only] [--dry-run] -Install the ${SKILL_NAME} Skill. Unless --skip-cli-install is used, the script -asks for confirmation before installing ${CLI_PACKAGE}@${CLI_VERSION} globally. +Install the ${SKILL_NAME} Skill and ${CLI_PACKAGE}@${CLI_VERSION}. Installation +is non-interactive by default; use --ask to require one confirmation for the +complete plan, or --skill-only to leave global npm packages unchanged. Options: --client Target client. Default: auto. --skills-dir Override the target Skills directory. - --skip-cli-install Install the Skill without offering to install the npm CLI. + --tag Git branch or tag to install. Default: ${TAG}. + --yes Install without prompting. This is the default. + --ask Show the complete plan and ask once before installation. + --skill-only Install only the Skill; do not install or change the npm CLI. + --skip-cli-install Alias for --skill-only. --dry-run Preview actions without changing files or packages. -h, --help Show this help. EOF @@ -86,7 +95,24 @@ while [ "$#" -gt 0 ]; do SKILLS_DIR_OVERRIDE="${1#--skills-dir=}" shift ;; - --skip-cli-install) + --tag) + [ "$#" -ge 2 ] || fail "--tag requires a value" + TAG="$2" + shift 2 + ;; + --tag=*) + TAG="${1#--tag=}" + shift + ;; + --yes) + ASSUME_YES=1 + shift + ;; + --ask) + ASSUME_YES=0 + shift + ;; + --skill-only|--skip-cli-install) SKIP_CLI_INSTALL=1 shift ;; @@ -128,50 +154,92 @@ installed_cli_version() { wallet-cli --version 2>/dev/null } -confirm_cli_install() { - if [ ! -r /dev/tty ]; then - info "No interactive terminal is available; skipping global npm installation." - return 1 - fi - - printf '\nInstall %s@%s globally with npm? [y/N] ' "$CLI_PACKAGE" "$CLI_VERSION" >/dev/tty - answer="" - IFS= read -r answer /dev/tty; } 2>/dev/null; then + fail "--ask requires an interactive terminal; rerun with --yes or --dry-run." + fi + + printf '\nProceed with this installation? [y/N] ' >&3 + answer="" + IFS= read -r answer <&3 || fail "Unable to read confirmation from the terminal." + exec 3>&- + case "$answer" in + y|Y|yes|YES|Yes) ;; + *) fail "Installation canceled." ;; + esac +} + +install_cli() { + case "$CLI_ACTION" in + skip) + info "Left global npm packages unchanged." + return + ;; + keep) + info "${CLI_PACKAGE}@${CLI_VERSION} is already available." + return + ;; + esac + npm install --global --no-fund --no-audit "${CLI_PACKAGE}@${CLI_VERSION}" installed_version="$(installed_cli_version || true)" [ "$installed_version" = "$CLI_VERSION" ] || fail "Expected wallet-cli ${CLI_VERSION}, found ${installed_version:-unknown}." @@ -257,11 +325,8 @@ install_skill() { info "Installed Skill at $target" } -install_cli_if_approved - if [ "$DRY_RUN" = "1" ]; then SOURCE_DIR="/${SKILL_NAME}" - info "Would clone ${REPO} at ${TAG} into a temporary directory" else WORKDIR="$(mktemp -d 2>/dev/null || mktemp -d -t "${SKILL_NAME}-install")" clone_dir="$WORKDIR/skills" @@ -276,6 +341,17 @@ if [ "$CLIENT" = "auto" ]; then targets="$(detect_client)" fi +prepare_cli_install +show_plan + +if [ "$DRY_RUN" = "1" ]; then + printf '\nDry run complete; no Skill files or npm packages were changed.\n' + exit 0 +fi + +confirm_plan +install_cli + if [ -n "$SKILLS_DIR_OVERRIDE" ]; then install_skill "$SKILLS_DIR_OVERRIDE" elif [ "$targets" = "all" ]; then @@ -285,12 +361,10 @@ else install_skill "$(default_skills_dir "$targets")" fi -if [ "$DRY_RUN" = "1" ]; then - printf '\nDry run complete; no Skill files or npm packages were changed.\n' +printf '\n%s installed.\n' "$SKILL_NAME" +if [ "$CLI_ACTION" = "skip" ]; then + printf 'The npm CLI was left unchanged; install %s@%s before using the Skill.\n' \ + "$CLI_PACKAGE" "$CLI_VERSION" else - printf '\n%s installed.\n' "$SKILL_NAME" - printf 'Verify the CLI with: wallet-cli --version\n' - if [ "$(installed_cli_version || true)" != "$CLI_VERSION" ]; then - printf 'The npm CLI is not pinned to %s; install it explicitly before using the Skill.\n' "$CLI_VERSION" - fi + printf 'Verified CLI: wallet-cli %s\n' "$(installed_cli_version)" fi