Arch CLI Reference Guide

This guide covers the command surface exposed by arch-cli.

Global Options
Configuration Management
Account Operations
Program Deployment
Transaction Operations
Block and Network Info
APL Token Operations
Orchestration Commands
Bootnode Commands
Error Reference

Global Options

These options can be used with any command:

# Specify network mode
arch-cli --network-mode localnet|devnet|testnet|mainnet

# Use configuration profile
arch-cli --profile <PROFILE_NAME>

# Show help
arch-cli --help

# Show version
arch-cli --version

::::note All user-facing identifiers in arch-cli (addresses, public keys, transaction IDs, block hashes) are base58. ::::

Network Modes:

localnet: Local development network
devnet: Development network, and the default for arch-cli
testnet: Test network
mainnet: Production network

Configuration Management

Create Profile

Create a new configuration profile for connecting to Bitcoin, Arch, and Titan nodes:

arch-cli config create-profile <NAME> \
    --bitcoin-node-endpoint <URL> \
    --bitcoin-node-username <USERNAME> \
    --bitcoin-node-password <PASSWORD> \
    --bitcoin-network <NETWORK> \
    --arch-node-url <URL> \
    --titan-url <URL>

Arguments:

<NAME>: Name of the profile
--bitcoin-node-endpoint: Bitcoin node endpoint URL, for example http://127.0.0.1:18443
--bitcoin-node-username: Bitcoin node RPC username
--bitcoin-node-password: Bitcoin node RPC password
--bitcoin-network: Bitcoin network, such as mainnet, testnet, or regtest
--arch-node-url: Arch Network node URL
--titan-url: Titan node URL

Example (testnet):

arch-cli config create-profile testnet \
    --bitcoin-node-endpoint http://bitcoin-rpc.test.arch.network:80 \
    --bitcoin-node-username bitcoin \
    --bitcoin-node-password 0F_Ed53o4kR7nxh3xNaSQx-2M3TY16L55mz5y9fjdrk \
    --bitcoin-network testnet \
    --arch-node-url https://rpc.testnet.arch.network \
    --titan-url https://titan.testnet.arch.network

::::note Public Arch RPC endpoints:

Testnet: https://rpc.testnet.arch.network
Mainnet: https://rpc.mainnet.arch.network

For local development, use http://localhost:9002. ::::

List Profiles

arch-cli config list-profiles

Update Profile

arch-cli config update-profile <NAME> \
    [--bitcoin-node-endpoint <URL>] \
    [--bitcoin-node-username <USERNAME>] \
    [--bitcoin-node-password <PASSWORD>] \
    [--bitcoin-network <NETWORK>] \
    [--arch-node-url <URL>]

Set Default Profile

arch-cli config set-default-profile <NAME>

Delete Profile

arch-cli config delete-profile <NAME>

Account Operations

Create Account

Generate a new keypair, optionally funding the account from the faucet:

arch-cli account create \
    --keypair-path <PATH> \
    [--airdrop]

Airdrop

Request an airdrop of lamports to an account:

arch-cli account airdrop \
    (--keypair-path <PATH> | --account <PUBKEY> | --pubkey <PUBKEY>) \
    [--amount <LAMPORTS>]

The default amount is 1000000 lamports.

Show Account

Display account or program information:

arch-cli show <PUBKEY>

Change Account Owner

arch-cli account change-owner <ACCOUNT_ADDRESS> <NEW_OWNER> <PAYER_KEYPAIR_PATH>

Assign UTXO

arch-cli account assign-utxo <ACCOUNT_PUBKEY>

Program Deployment

Deploy a program to the network:

arch-cli deploy [ELF_PATH] [--generate-if-missing] [--fund-authority]

Arguments:

ELF_PATH: Optional path to the compiled ELF directory. If omitted, the CLI uses ./target/deploy.
--generate-if-missing: Generate missing program and authority keypairs in the deploy directory.
--fund-authority: Fund the generated authority account using the faucet.

::::note arch-cli does not expose generic program show or program call subcommands. Use arch-cli show <PUBKEY> to inspect an account or program, and use the SDK/RPC APIs to submit custom transactions. ::::

Transaction Operations

Transaction commands are grouped under tx.

arch-cli tx confirm <TX_ID>
arch-cli tx get <TX_ID>
arch-cli tx log-program-messages <TX_ID>

Block and Network Info

Get Block Height

arch-cli get-block-height

Get Block

Get a block by its base58 block hash:

arch-cli get-block <BLOCK_HASH>

Get Network Public Key

arch-cli get-network-pubkey <PUBKEY>

::::note The current CLI argument for get-network-pubkey is retained for compatibility, but the command fetches the network public key from the active node. ::::

APL Token Operations

Core Token Commands

# Create a mint
arch-cli token create-mint \
    --decimals <DECIMALS> \
    --mint-authority <AUTHORITY_PATH> \
    [--freeze-authority <AUTHORITY_PATH>] \
    [--mint-keypair-path <PATH>] \
    --keypair-path <PATH>

# Inspect a mint
arch-cli token show-mint <MINT_ADDRESS>

# Create a token account
arch-cli token create-account \
    --mint <MINT_ADDRESS> \
    --owner <OWNER_PATH> \
    --keypair-path <PATH>

# Inspect a token account
arch-cli token show-account <TOKEN_ACCOUNT_ADDRESS>

# Mint tokens
arch-cli token mint \
    <MINT_ADDRESS> \
    <AMOUNT> \
    --authority <AUTHORITY_PATH> \
    [--account-address <TOKEN_ACCOUNT_ADDRESS>] \
    [--auto-create-ata] \
    [--multisig <MULTISIG_ADDRESS>] \
    [--signers <SIGNER_PATHS>...] \
    [--keypair-path <PATH>]

# Transfer tokens
arch-cli token transfer \
    <SOURCE_ACCOUNT> \
    <DESTINATION_ACCOUNT> \
    <AMOUNT> \
    --owner <OWNER_PATH> \
    [--multisig <MULTISIG_ADDRESS>] \
    [--signers <SIGNER_PATHS>...] \
    [--keypair-path <PATH>]

Additional Token Commands

The CLI also exposes these token subcommands:

burn <ACCOUNT_ADDRESS> <AMOUNT> --owner <OWNER_PATH>
approve <ACCOUNT_ADDRESS> <DELEGATE_ADDRESS> <AMOUNT> --owner <OWNER_PATH>
revoke <ACCOUNT_ADDRESS> --owner <OWNER_PATH>
freeze-account <ACCOUNT_ADDRESS> --authority <AUTHORITY_PATH>
thaw-account <ACCOUNT_ADDRESS> --authority <AUTHORITY_PATH>
create-multisig <M> --signers <SIGNER_PATHS>... --keypair-path <PATH>
multisig-sign <MULTISIG_ADDRESS> <TRANSACTION> --keypair-path <PATH>
multisig-execute <MULTISIG_ADDRESS> <TRANSACTION> --signers <SIGNER_PATHS>... --keypair-path <PATH>
multisig-show <MULTISIG_ADDRESS>
balance <ACCOUNT_ADDRESS>
supply <MINT_ADDRESS>
accounts <MINT_ADDRESS>
mints
amount-to-ui <MINT_ADDRESS> <AMOUNT>
ui-to-amount <MINT_ADDRESS> <UI_AMOUNT>
transfer-checked <SOURCE_ACCOUNT> <DESTINATION_ACCOUNT> <AMOUNT> <DECIMALS> --owner <OWNER_PATH>
approve-checked <ACCOUNT_ADDRESS> <DELEGATE_ADDRESS> <AMOUNT> <DECIMALS> --owner <OWNER_PATH>
mint-to-checked <MINT_ADDRESS> <ACCOUNT_ADDRESS> <AMOUNT> <DECIMALS> --authority <AUTHORITY_PATH>
burn-checked <ACCOUNT_ADDRESS> <AMOUNT> <DECIMALS> --owner <OWNER_PATH>
set-authority <TARGET_ADDRESS> --authority-type <TYPE> --current-authority <PATH> [--new-authority <ADDRESS|none>]
close-account <ACCOUNT_ADDRESS> <DESTINATION_ADDRESS> --owner <OWNER_PATH>
batch-transfer <TRANSFERS_FILE> --keypair-path <PATH>
batch-mint <MINTS_FILE> --keypair-path <PATH>

Orchestration Commands

Start Local Environment

arch-cli orchestrate start \
    [--rebuild-titan] \
    [--local <ARCH_NETWORK_SOURCE_DIR>] \
    [--force-rebuild] \
    [--titan-image <IMAGE>] \
    [--no-bitcoind]

By default, this uses the published ghcr.io/arch-network/local_validator:latest Linux amd64 image and publishes the local validator RPC API on http://localhost:9002. On Apple Silicon Macs, Docker must run the image as linux/amd64; the bundled compose file pins that platform. Use --local <ARCH_NETWORK_SOURCE_DIR> when you need to build the local validator from a source checkout instead of using the published image.

Service Lifecycle

arch-cli orchestrate stop
arch-cli orchestrate validator-start
arch-cli orchestrate validator-stop
arch-cli orchestrate validator-restart
arch-cli orchestrate validator-status
arch-cli orchestrate reset
arch-cli orchestrate validator-reset

Mine Regtest Blocks

arch-cli orchestrate mine-blocks --num-blocks <COUNT>

Bootnode Commands

Manage the local bootnode whitelist:

arch-cli bootnode add-validator <PUBKEY> [BOOTNODE_PORT]
arch-cli bootnode remove-validator <PUBKEY> [BOOTNODE_PORT]
arch-cli bootnode fetch-whitelist [BOOTNODE_PORT]

The default bootnode RPC port is 19021.

Error Reference

Common Error Codes

Code	Description	Solution
`InvalidKeypair`	Invalid keypair format	Check keypair file path and format
`InsufficientFunds`	Not enough lamports	Request an airdrop or add funds
`AccountNotFound`	Account doesn't exist	Create the account first
`ProgramNotFound`	Program doesn't exist	Deploy the program first
`InvalidInstruction`	Invalid instruction data	Check instruction format and data
`NetworkError`	Network connection failed	Check network connectivity and endpoints

Troubleshooting

Connection Issues:

# Check if the node is ready
curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "is_node_ready", "params": []}'

# Check network version
curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "get_version", "params": []}'

Account Issues:

arch-cli show <PUBKEY>

Program Issues:

arch-cli show <PROGRAM_ID>

Best Practices

1. Configuration Management

Use profiles for different environments
Keep sensitive information secure
Use environment variables for passwords

2. Keypair Management

Store keypairs securely
Use different keypairs for different purposes
Backup important keypairs

3. Transaction Management

Confirm submitted transactions with arch-cli tx confirm <TX_ID>
Handle errors gracefully

4. Development Workflow

Use the local development environment for iterative work
Test thoroughly before deploying
Monitor logs for issues

Examples

Complete Development Setup

# 1. Start local environment
arch-cli orchestrate start

# 2. Create a profile
arch-cli config create-profile local \
    --bitcoin-node-endpoint http://127.0.0.1:18443 \
    --bitcoin-node-username bitcoin \
    --bitcoin-node-password bitcoinpass \
    --bitcoin-network regtest \
    --arch-node-url http://localhost:9002 \
    --titan-url http://localhost:3030

# 3. Set as default
arch-cli config set-default-profile local

# 4. Create and fund an account
arch-cli account create --keypair-path ~/my_account.key
arch-cli account airdrop --keypair-path ~/my_account.key

# 5. Deploy a program
arch-cli deploy target/deploy

# 6. Check status
arch-cli get-block-height

Token Operations

# 1. Create a token mint
arch-cli token create-mint \
    --decimals 9 \
    --mint-authority ~/mint_authority.key \
    --keypair-path ~/payer.key

# 2. Create a token account
arch-cli token create-account \
    --mint <MINT_ADDRESS> \
    --owner ~/owner.key \
    --keypair-path ~/payer.key

# 3. Mint tokens
arch-cli token mint \
    <MINT_ADDRESS> \
    1000000000 \
    --account-address <TOKEN_ACCOUNT> \
    --authority ~/mint_authority.key \
    --keypair-path ~/payer.key

# 4. Transfer tokens
arch-cli token transfer \
    <SOURCE_ACCOUNT> \
    <DESTINATION_ACCOUNT> \
    500000000 \
    --owner ~/owner.key \
    --keypair-path ~/payer.key

Arch CLI Reference Guide

Quick Start Guide

Program Development

Token Creation

RPC API Reference

Community Discord

Arch Examples

Community Discord

Arch Network Website

On this page