near-cli-rs

SKILL: near-cli-rs — 面向 AI Agent 的 NEAR Protocol CLI 参考

用途： 本文件供大模型生成非交互式 near 命令使用。当用户请求对应某项 CLI 操作时，请在此查找正确语法，构造完整的一行命令，先向用户展示并征求批准，然后执行。

规则： 始终生成从 near 到最后一个操作标记（send、display、now、create 等）的完整命令。绝不省略 network-config <NETWORK>。

版本： near-cli-rs v0.14+（已测试至 v0.30.x，2026-09）

来源： near/near-cli-rs · 版本发布 · docs.near.org/tools/cli

v0.24 以来的变更（v0.25–v0.30.x）

较新版本的 CLI 有一些值得了解的行为变更，生成命令时请注意：

• Gas 密钥（nearcore 2.13+）：交易可以使用 Gas 密钥签名；签名时会提示选择 nonce_index。near transaction sign-message 也支持使用 Gas 密钥签名。
• 后量子密钥（草案）：v0.28+ 可以生成 ML-DSA-65 密钥（ml-dsa-65: 密钥格式）；公钥显示中包含 ml-dsa-65-hash。此功能为实验性功能，通常应继续使用 ed25519。
• 已移除： 独立的 generate-keypair 命令（请改用 account import-account，并预先在本地生成密钥）。
• 新增命令： tokens send-ft-call（tokens 子命令中的 ft_transfer_call）；account import-account 可通过非交互方式操作现有账户；contract state-init 可在部署时初始化新合约的状态。
• 默认值变更： 函数调用的 Gas 限制已更新为 1000 TGas；合约范围内的 FT 列表功能有所改进（可查看账户中所有合约的 FT，而不再仅限于硬编码列表）。
• 全局哈希部署可安全重试；执行 account delete-account 前会验证受益账户。

如果你的 CLI 版本与此处生成的命令不一致，请使用 near --help / near <group> <subcommand> --help 核实确切语法。

---

命令语法

near [GLOBAL_FLAGS] <COMMAND_GROUP> [ENTITY_ARGS] <SUBCOMMAND> [SUB_ARGS] network-config <NETWORK> [SIGNING_OPTION] [FINAL_ACTION]

• 查看命令以以下参数结尾：now | at-block-height <N> | at-block-hash <HASH>
• 交易命令以签名选项结尾，后接 send 或 display
• 通过水龙头创建账户以 create 结尾
• 始终必须包含 network-config 关键字（即使是查看命令也不例外）

---

全局标志

标志	作用
--offline	在不访问网络的情况下创建/签名交易
--quiet	抑制进度输出（建议用于脚本）
--teach-me	打印所有 RPC 调用及其参数

---

网络和查看限定符

项目	值
内置网络	mainnet、testnet
自定义网络	near config show-connections 中的任意 <connection-name>
查看：最新区块	now
查看：指定高度	at-block-height <BLOCK_HEIGHT>
查看：指定哈希	at-block-hash <BLOCK_HASH>

---

金额和 Gas 格式

资产	格式	备注
NEAR	'1 NEAR' or '0.5 NEAR'	加引号，单位前有空格
yoctoNEAR	'1 yoctoNEAR'	许多合约调用都需要此项存款
Gas	'30 Tgas' to '300 Tgas'	默认值为 '100 Tgas'，最大值为 '300 Tgas'
FT 金额	'10 usn'	数字 + FT 符号，加引号
全部 FT	all	转出全部余额

---

签名选项参考

在任何交易命令中，将 <SIGNING_OPTION> 替换为以下选项之一：

选项	完整语法
OS 密钥链（推荐）	sign-with-keychain send
旧版密钥链（~/.near-credentials/）	sign-with-legacy-keychain send
Ledger 硬件钱包	sign-with-ledger send
明文私钥	sign-with-plaintext-private-key --signer-public-key ed25519:<PUBKEY> --signer-private-key ed25519:<PRIVKEY> send
访问密钥文件	sign-with-access-key-file /path/to/key.json send
助记词	sign-with-seed-phrase 'word1 ... word12' --seed-phrase-hd-path 'm/44'"'"'/397'"'"'/0'"'"'' send
MPC	sign-with-mpc send
生成未签名交易（稍后签名）	sign-later

将 send 替换为 display，即可打印签名后的交易（base64 编码），而不进行广播。

---

account 命令

view-account-summary

# Current block
near account view-account-summary <ACCOUNT_ID> network-config <NETWORK> now

# Specific block height
near account view-account-summary <ACCOUNT_ID> network-config <NETWORK> at-block-height <BLOCK_HEIGHT>

# Specific block hash
near account view-account-summary <ACCOUNT_ID> network-config <NETWORK> at-block-hash <BLOCK_HASH>

import-account

# Using seed phrase (non-interactive)
near account import-account using-seed-phrase '<SEED_PHRASE>' --seed-phrase-hd-path 'm/44'"'"'/397'"'"'/0'"'"'' network-config <NETWORK>

# Using private key
near account import-account using-private-key ed25519:<PRIVATE_KEY> network-config <NETWORK>

# NOTE: using-web-wallet requires a browser redirect — not suitable for non-interactive use

export-account

# Export as seed phrase
near account export-account <ACCOUNT_ID> using-seed-phrase network-config <NETWORK>

# Export as private key
near account export-account <ACCOUNT_ID> using-private-key network-config <NETWORK>

create-account

# Testnet faucet (testnet only) — autogenerate keypair
near account create-account sponsor-by-faucet-service <NEW_ACCOUNT_ID> autogenerate-new-keypair save-to-keychain network-config testnet create

# Testnet faucet — use known seed phrase
near account create-account sponsor-by-faucet-service <NEW_ACCOUNT_ID> use-manually-provided-seed-phrase '<SEED_PHRASE>' network-config testnet create

# Testnet faucet — use known public key
near account create-account sponsor-by-faucet-service <NEW_ACCOUNT_ID> use-manually-provided-public-key ed25519:<PUBKEY> network-config testnet create

# Fund-myself: create sub-account (signer is implicit from keychain)
near account create-account fund-myself <NEW_ACCOUNT_ID> '<INITIAL_BALANCE>' autogenerate-new-keypair save-to-keychain sign-as network-config <NETWORK> sign-with-keychain send

# Fund-myself: create account specifying explicit signer
near account create-account fund-myself <NEW_ACCOUNT_ID> '<INITIAL_BALANCE>' autogenerate-new-keypair save-to-keychain sign-as <SIGNER_ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

# Fund-myself: use known seed phrase for new account
near account create-account fund-myself <NEW_ACCOUNT_ID> '<INITIAL_BALANCE>' use-manually-provided-seed-phrase '<SEED_PHRASE>' sign-as <SIGNER_ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

# Fund-myself: use known public key for new account
near account create-account fund-myself <NEW_ACCOUNT_ID> '<INITIAL_BALANCE>' use-manually-provided-public-key ed25519:<PUBKEY> sign-as <SIGNER_ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

delete-account

near account delete-account <ACCOUNT_ID> beneficiary <BENEFICIARY_ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

list-keys

near account list-keys <ACCOUNT_ID> network-config <NETWORK> now

get-public-key

# From seed phrase
near account get-public-key from-seed-phrase '<SEED_PHRASE>' --seed-phrase-hd-path "m/44'/397'/0'"

# From plaintext private key
near account get-public-key from-plaintext-private-key ed25519:<PRIVATE_KEY>

# From OS keychain
near account get-public-key from-keychain <ACCOUNT_ID> network-config <NETWORK>

# From legacy keychain
near account get-public-key from-legacy-keychain <ACCOUNT_ID> network-config <NETWORK>

# From Ledger (requires 5-component path)
near account get-public-key from-ledger --seed-phrase-hd-path "m/44'/397'/0'/0'/1'"

add-key

# Add full-access key (provide existing public key)
near account add-key <ACCOUNT_ID> grant-full-access use-manually-provided-public-key ed25519:<PUBKEY> network-config <NETWORK> sign-with-keychain send

# Add function-call-only key (autogenerate keypair)
near account add-key <ACCOUNT_ID> grant-function-call-access --allowance '<ALLOWANCE>' --contract-account-id <CONTRACT_ID> --function-names '<METHOD1>, <METHOD2>' autogenerate-new-keypair save-to-keychain network-config <NETWORK> sign-with-keychain send

# Add function-call-only key (allow all methods on contract)
near account add-key <ACCOUNT_ID> grant-function-call-access --allowance '<ALLOWANCE>' --contract-account-id <CONTRACT_ID> --function-names '' use-manually-provided-public-key ed25519:<PUBKEY> network-config <NETWORK> sign-with-keychain send

delete-keys

near account delete-keys <ACCOUNT_ID> public-keys ed25519:<PUBKEY> network-config <NETWORK> sign-with-keychain send

manage-storage-deposit

# View storage balance
near account manage-storage-deposit <CONTRACT_ID> view-balance <ACCOUNT_ID> network-config <NETWORK> now

# Deposit storage
near account manage-storage-deposit <CONTRACT_ID> deposit <ACCOUNT_ID> '<AMOUNT>' sign-as <SIGNER_ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

# Withdraw from storage
near account manage-storage-deposit <CONTRACT_ID> withdraw '<AMOUNT>' sign-as <ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

update-social-profile

# Update profile with JSON args
near account update-social-profile <ACCOUNT_ID> json-args '{"name":"<NAME>","image":{"ipfs_cid":"<CID>"}}' sign-as <ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

# Update profile from file
near account update-social-profile <ACCOUNT_ID> file-args /path/to/profile.json sign-as <ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

---

tokens 命令

view-near-balance

near tokens <ACCOUNT_ID> view-near-balance network-config <NETWORK> now

view-ft-balance

near tokens <ACCOUNT_ID> view-ft-balance <FT_CONTRACT_ID> network-config <NETWORK> now

view-nft-assets

near tokens <ACCOUNT_ID> view-nft-assets <NFT_CONTRACT_ID> network-config <NETWORK> now

send-near

near tokens <SENDER_ACCOUNT_ID> send-near <RECEIVER_ACCOUNT_ID> '<AMOUNT>' network-config <NETWORK> sign-with-keychain send

send-ft

# Send specific amount
near tokens <SENDER_ACCOUNT_ID> send-ft <FT_CONTRACT_ID> <RECEIVER_ACCOUNT_ID> '<AMOUNT>' memo '<MEMO>' network-config <NETWORK> sign-with-keychain send

# Send all tokens (with optional custom gas/deposit)
near tokens <SENDER_ACCOUNT_ID> send-ft <FT_CONTRACT_ID> <RECEIVER_ACCOUNT_ID> all memo '' --prepaid-gas '300.0 Tgas' --attached-deposit '1 yoctoNEAR' network-config <NETWORK> sign-with-keychain send

注意：默认的 prepaid-gas 为 '100.0 Tgas'，attached-deposit 为 '1 yoctoNEAR'。

send-nft

near tokens <SENDER_ACCOUNT_ID> send-nft <NFT_CONTRACT_ID> <RECEIVER_ACCOUNT_ID> <TOKEN_ID> --prepaid-gas '300.0 Tgas' --attached-deposit '1 yoctoNEAR' network-config <NETWORK> sign-with-keychain send

---

staking 命令

validator-list

near staking validator-list network-config <NETWORK>

delegation

# View delegated stake balance
near staking delegation <ACCOUNT_ID> view-balance <POOL_ID> network-config <NETWORK> now

# Deposit and stake (send NEAR to pool and immediately stake)
near staking delegation <ACCOUNT_ID> deposit-and-stake '<AMOUNT>' <POOL_ID> network-config <NETWORK> sign-with-keychain send

# Stake previously deposited tokens
near staking delegation <ACCOUNT_ID> stake '<AMOUNT>' <POOL_ID> network-config <NETWORK> sign-with-keychain send

# Stake all previously deposited or unstaked tokens
near staking delegation <ACCOUNT_ID> stake-all <POOL_ID> network-config <NETWORK> sign-with-keychain send

# Unstake a specific amount
near staking delegation <ACCOUNT_ID> unstake '<AMOUNT>' <POOL_ID> network-config <NETWORK> sign-with-keychain send

# Unstake everything
near staking delegation <ACCOUNT_ID> unstake-all <POOL_ID> network-config <NETWORK> sign-with-keychain send

# Withdraw a specific amount (after unstaking + ~2 epoch wait)
near staking delegation <ACCOUNT_ID> withdraw '<AMOUNT>' <POOL_ID> network-config <NETWORK> sign-with-keychain send

# Withdraw all available unstaked tokens
near staking delegation <ACCOUNT_ID> withdraw-all <POOL_ID> network-config <NETWORK> sign-with-keychain send

**注意：**未质押的资金需要约 2 个 epoch（约 48 小时）才能提取。

---

contract 命令

call-function（查看/只读）

# With JSON args
near contract call-function as-read-only <CONTRACT_ID> <METHOD_NAME> json-args '{"key":"value"}' network-config <NETWORK> now

# With empty args
near contract call-function as-read-only <CONTRACT_ID> <METHOD_NAME> empty-args network-config <NETWORK> now

# With text args
near contract call-function as-read-only <CONTRACT_ID> <METHOD_NAME> text-args '<STRING>' network-config <NETWORK> now

# With base64 args
near contract call-function as-read-only <CONTRACT_ID> <METHOD_NAME> base64-args '<BASE64>' network-config <NETWORK> now

call-function（交易/更改状态）

# With JSON args
near contract call-function as-transaction <CONTRACT_ID> <METHOD_NAME> json-args '{"key":"value"}' prepaid-gas '<GAS>' attached-deposit '<DEPOSIT>' sign-as <SIGNER_ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

# With empty args
near contract call-function as-transaction <CONTRACT_ID> <METHOD_NAME> empty-args prepaid-gas '<GAS>' attached-deposit '<DEPOSIT>' sign-as <SIGNER_ACCOUNT_ID> network-config <NETWORK> sign-with-keychain send

deploy

# Deploy without init call
near contract deploy <ACCOUNT_ID> use-file /path/to/contract.wasm without-init-call network-config <NETWORK> sign-with-keychain send

# Deploy with init call
near contract deploy <ACCOUNT_ID> use-file /path/to/contract.wasm with-init-call <INIT_METHOD> json-args '{}' prepaid-gas '100 Tgas' attached-deposit '0 NEAR' network-config <NETWORK> sign-with-keychain send

inspect

near contract inspect <CONTRACT_ID> network-config <NETWORK> now

verify

near contract verify deployed-at <CONTRACT_ID> network-config <NETWORK> now

download-abi

near contract download-abi <CONTRACT_ID> save-to-file <OUTPUT_FILE_PATH> network-config <NETWORK> now

download-wasm

near contract download-wasm <CONTRACT_ID> save-to-file <OUTPUT_FILE_PATH> network-config <NETWORK> now

view-storage

# View all storage as JSON
near contract view-storage <CONTRACT_ID> all as-json network-config <NETWORK> now

# View storage filtered by key prefix (string)
near contract view-storage <CONTRACT_ID> keys-start-with-string '<PREFIX>' as-json network-config <NETWORK> now

# View storage filtered by key prefix (base64)
near contract view-storage <CONTRACT_ID> keys-start-with-bytes-as-base64 '<BASE64_PREFIX>' as-json network-config <NETWORK> now

---

transaction 命令

view-status

near transaction view-status <TX_HASH> network-config <NETWORK>

reconstruct-transaction

near transaction reconstruct-transaction <TX_HASH> network-config <NETWORK>

sign-transaction

near transaction sign-transaction '<UNSIGNED_TX_BASE64>' network-config <NETWORK> sign-with-keychain send

send-signed-transaction

near transaction send-signed-transaction '<SIGNED_TX_BASE64>' network-config <NETWORK>

print-transaction

# Print signed transaction fields
near transaction print-transaction signed '<SIGNED_TX_BASE64>'

# Print unsigned transaction fields
near transaction print-transaction unsigned '<UNSIGNED_TX_BASE64>'

send-meta-transaction

near transaction send-meta-transaction '<SIGNED_DELEGATE_BASE64>' network-config <NETWORK>

---

config 命令

show-connections

near config show-connections

add-connection

near config add-connection --network-name <NETWORK_NAME> --connection-name <CONNECTION_NAME> --rpc-url <RPC_URL> --wallet-url <WALLET_URL> --explorer-transaction-url <EXPLORER_TX_URL> [--rpc-api-key '<API_KEY>'] [--linkdrop-account-id <LINKDROP_ID>] [--faucet-url <FAUCET_URL>] [--meta-transaction-relayer-url <RELAYER_URL>]

delete-connection

near config delete-connection <CONNECTION_NAME>

---

常见模式（速查手册）

最常用任务的快速参考单行命令。请将占位符替换为实际值。

1. 查看 NEAR 余额

near tokens alice.near view-near-balance network-config mainnet now

2. 转账 NEAR 代币

near tokens alice.near send-near bob.near '5 NEAR' network-config mainnet sign-with-keychain send

3. 查看账户详情

near account view-account-summary alice.near network-config mainnet now

4. 列出访问密钥

near account list-keys alice.near network-config mainnet now

5. 发送同质化代币

near tokens alice.near send-ft usdt.tether-token.near bob.near '10 USDT' memo '' network-config mainnet sign-with-keychain send

6. 查看 FT 余额

near tokens alice.near view-ft-balance usdt.tether-token.near network-config mainnet now

7. 调用只读合约方法

near contract call-function as-read-only wrap.near ft_balance_of json-args '{"account_id":"alice.near"}' network-config mainnet now

8. 调用会改变状态的合约方法

near contract call-function as-transaction wrap.near ft_transfer json-args '{"receiver_id":"bob.near","amount":"1000000000000000000000000"}' prepaid-gas '100 Tgas' attached-deposit '1 yoctoNEAR' sign-as alice.near network-config mainnet sign-with-keychain send

9. 向验证者质押 NEAR

near staking delegation alice.near deposit-and-stake '10 NEAR' aurora.pool.near network-config mainnet sign-with-keychain send

10. 从验证者处取消质押

near staking delegation alice.near unstake-all aurora.pool.near network-config mainnet sign-with-keychain send

11. 提取未质押的 NEAR（等待约 2 个 epoch 后）

near staking delegation alice.near withdraw-all aurora.pool.near network-config mainnet sign-with-keychain send

12. 创建 testnet 账户（由水龙头注资）

near account create-account sponsor-by-faucet-service myaccount.testnet autogenerate-new-keypair save-to-keychain network-config testnet create

13. 创建子账户（自行注资）

near account create-account fund-myself sub.alice.testnet '1 NEAR' autogenerate-new-keypair save-to-keychain sign-as alice.testnet network-config testnet sign-with-keychain send

14. 部署合约

near contract deploy mycontract.testnet use-file ./contract.wasm without-init-call network-config testnet sign-with-keychain send

15. 删除访问密钥

near account delete-keys alice.testnet public-keys ed25519:<PUBKEY_TO_REMOVE> network-config testnet sign-with-keychain send

16. 添加完全访问权限密钥

near account add-key alice.testnet grant-full-access use-manually-provided-public-key ed25519:<NEW_PUBKEY> network-config testnet sign-with-keychain send

---

离线模式与脚本编写技巧

离线签名工作流（隔离网络／两台机器）

# Machine A (offline): produce signed tx in base64 without broadcasting
near --offline tokens alice.near send-near bob.near '1 NEAR' network-config mainnet sign-with-seed-phrase '<SEED_PHRASE>' --seed-phrase-hd-path 'm/44'"'"'/397'"'"'/0'"'"'' display

# Machine B (online): broadcast the base64 tx
near transaction send-signed-transaction '<SIGNED_TX_BASE64>' network-config mainnet

延后签名工作流

# Step 1: produce unsigned base64 tx
near tokens alice.near send-near bob.near '1 NEAR' network-config mainnet sign-later

# Step 2: sign it (outputs signed base64)
near transaction sign-transaction '<UNSIGNED_TX_BASE64>' network-config mainnet sign-with-keychain display

# Step 3: broadcast
near transaction send-signed-transaction '<SIGNED_TX_BASE64>' network-config mainnet

脚本编写技巧

• 在脚本中始终添加 --quiet，以禁止显示进度输出
• 始终为金额加引号：'1 NEAR'、'0.5 NEAR'、'1 yoctoNEAR'
• 助记词 HD 路径的 shell 转义：'m/44'"'"'/397'"'"'/0'"''
• 使用 display 而不是 send，以便在广播前检查已签名的交易

---

密钥格式参考

项目	格式	示例
公钥	ed25519:<BASE58>	ed25519:8h7kFK4...
私钥	ed25519:<BASE58>	ed25519:2qM8v3N...
交易哈希	44 字符 base58	F3eZmht...
命名账户	name.near / name.testnet	alice.near
隐式账户	64 字符小写十六进制	a4b05ef3...
标准 HD 路径	m/44'/397'/0'	NEAR BIP44
Ledger HD 路径	m/44'/397'/0'/0'/N'	Ledger 要求 5 个组件
PQ 公钥（v0.28+，草案）	ml-dsa-65:<BASE58>	后量子密钥；实验性

---

常见错误

错误	可能原因／解决方法
"Account does not exist"	网络错误，或账户尚未注资
"Access key not found"	使用 sign-with-legacy-keychain 或 sign-with-seed-phrase
"Exceeded prepaid gas"	增加 gas：'300 Tgas'
FT transfer fails silently	FT ft_transfer 需要 attached-deposit '1 yoctoNEAR'
"Method not found"	使用 near contract inspect 检查方法名称
Seed phrase HD path error	转义单引号：'m/44'"'"'/397'"'"'/0'"'"''