Skills
skills/iskysun96/aptos-agent-skills/use-aptos-cli

use-aptos-cli

SKILL.md

Use Aptos CLI Skill

Overview

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

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

Core Commands

Project Initialization

# Create new Move project
aptos move init --name <project_name>

# Example
aptos move init --name my_marketplace

Compilation

# Compile Move modules
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
aptos move compile --save-metadata

Testing

# 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
aptos move coverage source --module marketplace

Publishing/Deployment

IMPORTANT: Use deploy-object to deploy as objects (modern pattern), NOT publish (creates resource account).

# ✅ CORRECT: Deploy as object (recommended)
aptos move deploy-object --address-name <named_address>

# Example: Deploy marketplace contract as object
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:

[addresses]
marketplace_addr = "_"

The CLI will override this with the actual deployment address.

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

# ❌ 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.

Account Management

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

Funding Accounts (Devnet/Testnet)

Use the web faucet (requires login):

  1. Get your account address: aptos account list --profile testnet
  2. Go to: https://aptos.dev/network/faucet?address=<your_address>
  3. Login and request testnet/devnet APT
  4. Verify balance: aptos account balance --profile testnet

Note: The CLI command aptos account fund-with-faucet is deprecated. Use the web faucet instead.

Running Functions

# Run entry function
aptos move run \
    --function-id <address>::<module>::<function> \
    --args <arg1> <arg2> ...

# Example: Create 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>

View Functions

# Call view function (read-only)
aptos move view \
    --function-id <address>::<module>::<function> \
    --args <arg1> <arg2>

# Example: Get NFT name
aptos move view \
    --function-id 0xCAFE::nft::get_nft_name \
    --args address:0x123

Documentation

# Generate documentation
aptos move document

# Generate and open in browser
aptos move document --open

Cleanup

# Clean build artifacts
aptos move clean

Advanced Commands

Scripting

# Run Move script
aptos move run-script \
    --compiled-script-path <path_to_compiled_script>

Prove (Formal Verification)

# Run Move prover
aptos move prove

# Prove specific module
aptos move prove --module <module_name>

Transaction Simulation

# Simulate transaction without submitting
aptos move run \
    --function-id <address>::<module>::<function> \
    --args <args> \
    --simulate

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.

Config File (~/.aptos/config.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

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

# Set default profile
export APTOS_PROFILE=testnet

Argument Types

Primitive Types

# u8, u16, u32, u64, u128, u256
--args u64:1000

# bool
--args bool:true

# address
--args address:0x1

Complex Types

# string (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\"]"

Object Types

# Object address (for Object<T> parameters)
--args address:0x123abc...

Network URLs

Devnet

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

Testnet

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

Mainnet

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

Troubleshooting Commands

Check CLI Version

aptos --version

Update CLI

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

Clear Cache

# Remove build directory
rm -rf build/

# Recompile
aptos move compile

Verbose Output

# Add --verbose flag to any command
aptos move compile --verbose
aptos move test --verbose

Common Error Solutions

"Package dependencies not resolved"

# Solution: Fetch dependencies
aptos move compile

"Address not found in named addresses"

# Solution: Specify named addresses
aptos move compile --named-addresses my_addr=0xCAFE

"Insufficient funds"

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

  1. Get address: aptos account list --profile testnet
  2. Go to: https://aptos.dev/network/faucet?address=<your_address>
  3. Login and request APT

"Module already published"

# Solution: Use upgrade-object with original object address
aptos move upgrade-object \
    --address-name my_addr \
    --object-address <object_address_from_initial_deploy>

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

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

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

References

Official Documentation:

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.

Weekly Installs
15
Repository
iskysun96/aptos…t-skills
GitHub Stars
10
First Seen
Feb 5, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
opencode13
gemini-cli13
github-copilot13
codex13
amp13
kimi-cli13