use-aptos-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use Aptos CLI Skill

使用Aptos CLI技能

Overview

概述

Comprehensive reference for Aptos CLI commands used in Move development workflow.

Installation: https://aptos.dev/build/cli

这是Move开发工作流中使用的Aptos CLI命令的综合参考。

安装地址： https://aptos.dev/build/cli

Core Commands

核心命令

Project Initialization

项目初始化

bash

undefined

bash

undefined

Create new Move project

创建新的Move项目

aptos move init --name <project_name>

Example

示例

aptos move init --name my_marketplace

undefined

aptos move init --name my_marketplace

undefined

Compilation

编译

bash

undefined

bash

undefined

Compile Move modules

编译Move模块

aptos move compile

Compile with specific named addresses

使用指定命名地址编译

aptos move compile --named-addresses my_addr=0xCAFE

Compile without fetching latest deps (faster)

不获取最新依赖进行编译（速度更快）

aptos move compile --skip-fetch-latest-git-deps

Generate ABI

生成ABI

aptos move compile --save-metadata

undefined

aptos move compile --save-metadata

undefined

Testing

测试

bash

undefined

bash

undefined

Run all tests

运行所有测试

aptos move test

Run specific test

运行指定测试

aptos move test --filter test_name

Run tests with coverage

带覆盖率检测运行测试

aptos move test --coverage

Generate coverage summary

生成覆盖率摘要

aptos move coverage summary

Generate detailed coverage report for module

生成模块的详细覆盖率报告

aptos move coverage source --module <module_name>

Example: View coverage for marketplace module

示例：查看marketplace模块的覆盖率

aptos move coverage source --module marketplace

undefined

aptos move coverage source --module marketplace

undefined

Publishing/Deployment

发布/部署

IMPORTANT: Use

deploy-object

to deploy as objects (modern pattern), NOT

publish

(creates resource account).

bash

undefined

重要提示： 使用

deploy-object

以对象形式部署（现代模式），不要使用

publish

（会创建资源账户）。

bash

undefined

✅ CORRECT: Deploy as object (recommended)

✅ 正确方式：以对象形式部署（推荐）

aptos move deploy-object --address-name <named_address>

Example: Deploy marketplace contract as object

示例：将marketplace合约以对象形式部署

aptos move deploy-object --address-name marketplace_addr

Deploy with auto-confirm (skips yes/no prompts)

自动确认部署（跳过确认提示）

aptos move deploy-object --address-name marketplace_addr --assume-yes

Deploy to specific network

部署到指定网络

aptos move deploy-object --address-name marketplace_addr --network testnet aptos move deploy-object --address-name marketplace_addr --network mainnet

Deploy with specific profile

使用指定配置文件部署

aptos move deploy-object --address-name marketplace_addr --profile my_profile

Upgrade existing object deployment

升级已部署的对象

aptos move upgrade-object
--address-name marketplace_addr
--object-address 0x123abc...

Upgrade with auto-confirm

自动确认升级

aptos move upgrade-object
--address-name marketplace_addr
--object-address 0x123abc...
--assume-yes


**Deployment Prompts:**

When deploying, the CLI will ask two questions:

1. **Gas confirmation**: "Do you want to submit a transaction for a range of [X - Y] Octas at a gas unit price of Z
   Octas? [yes/no]"
2. **Object address confirmation**: "Do you want to publish this package at object address 0x... [yes/no]"

To skip prompts, use `--assume-yes` flag (automatically answers "yes").

**Note on Move.toml:**

For object deployment, set named addresses to `_` (placeholder) in Move.toml:

```toml
[addresses]
marketplace_addr = "_"

The CLI will override this with the actual deployment address.

Legacy: Publishing to Resource Account (❌ Not recommended for new projects)

bash

undefined

aptos move upgrade-object
--address-name marketplace_addr
--object-address 0x123abc...
--assume-yes


**部署提示：**

部署时，CLI会询问两个问题：

1. **Gas费用确认**："是否提交一笔Gas费用范围为[X-Y] Octas、单价为Z Octas的交易？[是/否]"
2. **对象地址确认**："是否要在对象地址0x...发布此包？[是/否]"

要跳过提示，使用`--assume-yes`参数（自动回答“是”）。

**关于Move.toml的说明：**

对于对象部署，在Move.toml中将命名地址设置为`_`（占位符）：

```toml
[addresses]
marketplace_addr = "_"

CLI会自动将其替换为实际部署地址。

旧版：发布到资源账户（❌ 新项目不推荐使用）

bash

undefined

❌ OLD: Publish to resource account (legacy pattern)

❌ 旧方式：发布到资源账户（旧模式）

aptos move publish --named-addresses my_addr=default

This creates a resource account, which is deprecated.

此方式会创建资源账户，现已废弃。

Use deploy-object instead for modern object-based deployment.

请使用deploy-object进行现代的基于对象的部署。

undefined

undefined

Account Management

账户管理

bash

undefined

bash

undefined

Initialize new account

初始化新账户

aptos init

Initialize with specific network

在指定网络初始化账户

aptos init --network testnet

Create new account with profile

使用配置文件创建新账户

aptos init --profile my_profile

List account resources

列出账户资源

aptos account list --account <address>

Get account balance

查询账户余额

aptos account balance --account <address>

undefined

aptos account balance --account <address>

undefined

Funding Accounts (Devnet/Testnet)

账户充值（开发网/测试网）

Use the web faucet (requires login):

Get your account address:
```
aptos account list --profile testnet
```

Go to:

https://aptos.dev/network/faucet?address=<your_address>

Login and request testnet/devnet APT
Verify balance:
```
aptos account balance --profile testnet
```

Note: The CLI command

aptos account fund-with-faucet

is deprecated. Use the web faucet instead.

使用网页水龙头（需要登录）：

获取账户地址：
```
aptos account list --profile testnet
```

访问：

https://aptos.dev/network/faucet?address=<your_address>

登录并申请测试网/开发网APT代币
验证余额：
```
aptos account balance --profile testnet
```

注意： CLI命令

aptos account fund-with-faucet

已废弃，请使用网页水龙头替代。

Running Functions

运行函数

bash

undefined

bash

undefined

Run entry function

运行入口函数

aptos move run
--function-id <address>::<module>::<function>
--args <arg1> <arg2> ...

Example: Create NFT

示例：创建NFT

aptos move run
--function-id 0xCAFE::nft::mint_nft
--args string:"My NFT" string:"Description" string:"https://uri.com"

Run with type arguments

带类型参数运行函数

aptos move run
--function-id <address>::<module>::<function>
--type-args <type1> <type2>
--args <arg1> <arg2>

undefined

aptos move run
--function-id <address>::<module>::<function>
--type-args <type1> <type2>
--args <arg1> <arg2>

undefined

View Functions

查看函数

bash

undefined

bash

undefined

Call view function (read-only)

调用查看函数（只读）

aptos move view
--function-id <address>::<module>::<function>
--args <arg1> <arg2>

Example: Get NFT name

示例：获取NFT名称

aptos move view
--function-id 0xCAFE::nft::get_nft_name
--args address:0x123

undefined

aptos move view
--function-id 0xCAFE::nft::get_nft_name
--args address:0x123

undefined

Documentation

文档生成

bash

undefined

bash

undefined

Generate documentation

生成文档

aptos move document

Generate and open in browser

生成文档并在浏览器中打开

aptos move document --open

undefined

aptos move document --open

undefined

Cleanup

清理

bash

undefined

bash

undefined

Clean build artifacts

清理构建产物

aptos move clean

undefined

aptos move clean

undefined

Advanced Commands

高级命令

Scripting

脚本运行

bash

undefined

bash

undefined

Run Move script

运行Move脚本

aptos move run-script
--compiled-script-path <path_to_compiled_script>

undefined

aptos move run-script
--compiled-script-path <path_to_compiled_script>

undefined

Prove (Formal Verification)

形式验证（Prove）

bash

undefined

bash

undefined

Run Move prover

运行Move验证器

aptos move prove

Prove specific module

验证指定模块

aptos move prove --module <module_name>

undefined

aptos move prove --module <module_name>

undefined

Transaction Simulation

交易模拟

bash

undefined

bash

undefined

Simulate transaction without submitting

模拟交易但不提交

aptos move run
--function-id <address>::<module>::<function>
--args <args>
--simulate

undefined

aptos move run
--function-id <address>::<module>::<function>
--args <args>
--simulate

undefined

Configuration

配置

Security: NEVER read this file from the user's filesystem. The structure below is for reference only. Always use
"0x..."
placeholders for private key values.

安全提示： 切勿读取用户文件系统中的此文件。以下结构仅作参考。请始终使用
"0x..."
作为私钥值的占位符。

Config File (~/.aptos/config.yaml)

配置文件 (~/.aptos/config.yaml)

yaml

profiles:
  default:
    private_key: "0x..."
    public_key: "0x..."
    account: "0x..."
    rest_url: "https://fullnode.devnet.aptoslabs.com/v1"
    faucet_url: "https://faucet.devnet.aptoslabs.com"

  testnet:
    private_key: "0x..."
    public_key: "0x..."
    account: "0x..."
    rest_url: "https://fullnode.testnet.aptoslabs.com/v1"
    faucet_url: "https://faucet.testnet.aptoslabs.com"

  mainnet:
    private_key: "0x..."
    public_key: "0x..."
    account: "0x..."
    rest_url: "https://fullnode.mainnet.aptoslabs.com/v1"

yaml

profiles:
  default:
    private_key: "0x..."
    public_key: "0x..."
    account: "0x..."
    rest_url: "https://fullnode.devnet.aptoslabs.com/v1"
    faucet_url: "https://faucet.devnet.aptoslabs.com"

  testnet:
    private_key: "0x..."
    public_key: "0x..."
    account: "0x..."
    rest_url: "https://fullnode.testnet.aptoslabs.com/v1"
    faucet_url: "https://faucet.testnet.aptoslabs.com"

  mainnet:
    private_key: "0x..."
    public_key: "0x..."
    account: "0x..."
    rest_url: "https://fullnode.mainnet.aptoslabs.com/v1"

Switching Profiles

切换配置文件

bash

undefined

bash

undefined

Use specific profile

使用指定配置文件

aptos --profile testnet move publish --named-addresses my_addr=0x123

Set default profile

设置默认配置文件

export APTOS_PROFILE=testnet

undefined

export APTOS_PROFILE=testnet

undefined

Argument Types

参数类型

Primitive Types

基础类型

bash

undefined

bash

undefined

u8, u16, u32, u64, u128, u256

--args u64:1000

bool

布尔值

--args bool:true

address

地址

--args address:0x1

undefined

--args address:0x1

undefined

Complex Types

复杂类型

bash

undefined

bash

undefined

string (UTF-8)

字符串（UTF-8）

--args string:"Hello World"

hex (raw bytes)

十六进制（原始字节）

--args hex:0x48656c6c6f

vector

数组

--args "u64:[1,2,3,4,5]"

vector of strings

字符串数组

--args "string:["one","two","three"]"

undefined

--args "string:["one","two","three"]"

undefined

Object Types

对象类型

bash

undefined

bash

undefined

Object address (for Object<T> parameters)

对象地址（用于Object<T>参数）

--args address:0x123abc...

undefined

--args address:0x123abc...

undefined

Network URLs

网络URL

Devnet

开发网（Devnet）

REST: https://fullnode.devnet.aptoslabs.com/v1
Faucet: https://faucet.devnet.aptoslabs.com
Explorer: https://explorer.aptoslabs.com/?network=devnet

REST: https://fullnode.devnet.aptoslabs.com/v1
水龙头: https://faucet.devnet.aptoslabs.com
浏览器: https://explorer.aptoslabs.com/?network=devnet

Testnet

测试网（Testnet）

REST: https://fullnode.testnet.aptoslabs.com/v1
Faucet: https://faucet.testnet.aptoslabs.com
Explorer: https://explorer.aptoslabs.com/?network=testnet

REST: https://fullnode.testnet.aptoslabs.com/v1
水龙头: https://faucet.testnet.aptoslabs.com
浏览器: https://explorer.aptoslabs.com/?network=testnet

Mainnet

主网（Mainnet）

REST: https://fullnode.mainnet.aptoslabs.com/v1
Explorer: https://explorer.aptoslabs.com/?network=mainnet

REST: https://fullnode.mainnet.aptoslabs.com/v1
浏览器: https://explorer.aptoslabs.com/?network=mainnet

Troubleshooting Commands

故障排查命令

Check CLI Version

检查CLI版本

bash

aptos --version

bash

aptos --version

Update CLI

更新CLI

bash

undefined

bash

undefined

Using cargo

使用cargo安装

cargo install --git https://github.com/aptos-labs/aptos-core.git aptos

Using prebuilt binaries

使用预编译二进制文件

Download from: https://github.com/aptos-labs/aptos-core/releases

下载地址：https://github.com/aptos-labs/aptos-core/releases

undefined

undefined

Clear Cache

清理缓存

bash

undefined

bash

undefined

Remove build directory

删除构建目录

rm -rf build/

Recompile

重新编译

aptos move compile

undefined

aptos move compile

undefined

Verbose Output

详细输出

bash

undefined

bash

undefined

Add --verbose flag to any command

在任意命令后添加--verbose参数

aptos move compile --verbose aptos move test --verbose

undefined

aptos move compile --verbose aptos move test --verbose

undefined

Common Error Solutions

常见错误解决方案

"Package dependencies not resolved"

bash

undefined

bash

undefined

Solution: Fetch dependencies

解决方案：获取依赖

aptos move compile

undefined

aptos move compile

undefined

"Address not found in named addresses"

bash

undefined

bash

undefined

Solution: Specify named addresses

解决方案：指定命名地址

aptos move compile --named-addresses my_addr=0xCAFE

undefined

aptos move compile --named-addresses my_addr=0xCAFE

undefined

"Insufficient funds"

Solution: Fund via web faucet (testnet/devnet):

Get address:
```
aptos account list --profile testnet
```

Go to:

https://aptos.dev/network/faucet?address=<your_address>

解决方案： 通过网页水龙头充值（测试网/开发网）：

获取地址：
```
aptos account list --profile testnet
```

访问：

https://aptos.dev/network/faucet?address=<your_address>

登录并申请APT代币

"Module already published"

bash

undefined

bash

undefined

Solution: Use upgrade-object with original object address

解决方案：使用upgrade-object并指定原始对象地址

aptos move upgrade-object
--address-name my_addr
--object-address <object_address_from_initial_deploy>

undefined

aptos move upgrade-object
--address-name my_addr
--object-address <object_address_from_initial_deploy>

undefined

Quick Reference

快速参考

Command	Purpose
`aptos move init`	Create new project
`aptos move compile`	Compile Move code
`aptos move test`	Run tests
`aptos move test --coverage`	Test with coverage
`aptos move deploy-object`	Deploy module (modern)
`aptos move upgrade-object`	Upgrade deployed module
`aptos move run`	Execute entry function
`aptos move view`	Call view function
`aptos account list`	View account resources
`aptos account balance`	Check account balance
`aptos init`	Initialize CLI config

命令	用途
`aptos move init`	创建新项目
`aptos move compile`	编译Move代码
`aptos move test`	运行测试
`aptos move test --coverage`	带覆盖率检测运行测试
`aptos move deploy-object`	部署模块（现代方式）
`aptos move upgrade-object`	升级已部署模块
`aptos move run`	执行入口函数
`aptos move view`	调用查看函数
`aptos account list`	查看账户资源
`aptos account balance`	检查账户余额
`aptos init`	初始化CLI配置

ALWAYS Rules

必须遵守的规则

✅ ALWAYS run
```
aptos move test --coverage
```
before deployment
✅ ALWAYS verify 100% coverage
✅ ALWAYS test on testnet before mainnet
✅ ALWAYS use named addresses (not hardcoded)
✅ ALWAYS specify network for deployment
✅ ALWAYS check CLI version is up-to-date

✅ 部署前必须运行
```
aptos move test --coverage
```
✅ 必须验证覆盖率达到100%
✅ 主网部署前必须在测试网测试
✅ 必须使用命名地址（而非硬编码）
✅ 部署时必须指定网络
✅ 必须确保CLI版本为最新

NEVER Rules

严禁操作

❌ NEVER deploy without testing
❌ NEVER skip coverage verification
❌ NEVER deploy directly to mainnet without testnet testing
❌ NEVER hardcode addresses in code
❌ NEVER commit private keys to git
❌ NEVER read or display contents of
```
~/.aptos/config.yaml
```
(contains private keys for all profiles)

❌ NEVER run commands that expose keys:

cat ~/.aptos/config.yaml

env | grep KEY

printenv

❌ NEVER display or repeat private key values — always use
```
"0x..."
```
as placeholder

❌ 未测试严禁部署
❌ 严禁跳过覆盖率验证
✅ 未在测试网测试严禁直接部署到主网
❌ 严禁在代码中硬编码地址
❌ 严禁将私钥提交到Git
❌ 严禁读取或显示
```
~/.aptos/config.yaml
```
的内容（包含所有配置文件的私钥）

❌ 严禁运行暴露密钥的命令：

cat ~/.aptos/config.yaml

、

env | grep KEY

、

printenv

❌ 严禁显示或重复私钥值——始终使用
```
"0x..."
```
作为占位符

References

参考资料

Official Documentation:

CLI Guide: https://aptos.dev/build/cli
Working with Move Contracts: https://aptos.dev/build/cli/working-with-move-contracts
CLI Reference: https://aptos.dev/build/cli/cli-reference

Related Skills:

```
scaffold-project
```
- Initialize projects
```
write-contracts
```
- Write modules to compile
```
generate-tests
```
- Create tests to run
```
deploy-contracts
```
- Deploy modules
```
troubleshoot-errors
```
- Fix CLI errors

Remember: Test locally, deploy to testnet, verify, then mainnet. Always use --coverage.

官方文档：

CLI指南：https://aptos.dev/build/cli
Move合约开发：https://aptos.dev/build/cli/working-with-move-contracts
CLI参考：https://aptos.dev/build/cli/cli-reference

相关技能：

```
scaffold-project
```
- 初始化项目
```
write-contracts
```
- 编写待编译的模块
```
generate-tests
```
- 创建待运行的测试
```
deploy-contracts
```
- 部署模块
```
troubleshoot-errors
```
- 修复CLI错误

注意： 先本地测试，再部署到测试网，验证后再部署到主网。始终使用--coverage参数。