Starkli Installation and Configuration

starkli is the CLI tool for interacting with Starknet. It handles account management, transaction signing, and contract invocations.

Prerequisites

  • macOS or Linux
  • An existing Starknet account (e.g. Argent X wallet)
  • Your account's private key

Installation

Install starkli using the official installer:

curl https://get.starkli.sh | sh

Restart your terminal or reload your shell configuration:

source ~/.zshrc

Run the updater to fetch the latest version:

starkliup

Verify installation:

starkli -V

Directory Structure

Create the directories for storing starkli configuration and key material:

mkdir -p ~/.config/starkli
mkdir -p ~/.starkli-wallets

For multi-account setups (e.g. validator operations with separate accounts per role), use a network-scoped layout:

mkdir -p ~/.starknet/mainnet/signers
mkdir -p ~/.starknet/mainnet/accounts
mkdir -p ~/.starknet/sepolia/signers
mkdir -p ~/.starknet/sepolia/accounts

Network Configuration

Mainnet

Create the profiles configuration:

cat << 'EOF' > ~/.config/starkli/profiles.toml
[default.networks.mainnet]
chain_id = "SN_MAIN"
provider = { type = "free", vendor = "blast" }
EOF

Set the default network:

export STARKNET_NETWORK="mainnet"
export STARKNET_RPC="https://starknet-mainnet.public.blastapi.io"

Sepolia (Testnet)

cat << 'EOF' > ~/.config/starkli/profiles.toml
[default.networks.sepolia]
chain_id = "SN_SEPOLIA"
provider = { type = "free", vendor = "blast" }
EOF

export STARKNET_NETWORK="sepolia"
export STARKNET_RPC="https://starknet-sepolia.drpc.org"

Add the exports to your ~/.zshrc to persist across sessions.

Account Setup

Create Encrypted Keystore

Convert a plain text private key into an encrypted keystore:

starkli signer keystore from-key ~/.starkli-wallets/keystore.json

You will be prompted to enter your private key and set an encryption password.

Fetch Account Descriptor

Fetch your account details from the network:

starkli account fetch YOUR_ACCOUNT_ADDRESS --output ~/.starkli-wallets/account.json

Replace YOUR_ACCOUNT_ADDRESS with your Starknet account address.

Set Environment Variables

export STARKNET_KEYSTORE="$HOME/.starkli-wallets/keystore.json"
export STARKNET_ACCOUNT="$HOME/.starkli-wallets/account.json"

Add these to your ~/.zshrc to persist across sessions.

Creating a New Account

To create a fresh account using starkli directly:

ACCOUNT=my-account
starkli signer keystore new ~/.starknet/${STARKNET_NETWORK}/signers/${ACCOUNT}.json
starkli account argent init \
    --keystore=~/.starknet/${STARKNET_NETWORK}/signers/${ACCOUNT}.json \
    ~/.starknet/${STARKNET_NETWORK}/accounts/${ACCOUNT}.json

Fund the account with ETH, then deploy it:

starkli account deploy \
    --keystore=~/.starknet/${STARKNET_NETWORK}/signers/${ACCOUNT}.json \
    ~/.starknet/${STARKNET_NETWORK}/accounts/${ACCOUNT}.json

Verification

Check account balance:

starkli balance YOUR_ACCOUNT_ADDRESS

Check account nonce:

starkli nonce YOUR_ACCOUNT_ADDRESS

Check a transaction receipt:

starkli transaction-receipt TRANSACTION_HASH

Troubleshooting

  1. Network errors: Verify your network configuration and that you are targeting the correct network (mainnet vs sepolia).
  2. Signing failures: Ensure keystore path is correct, verify you are using the correct password, check that the account address matches the keystore's public key.
  3. Environment variables not working: Reload your shell with source ~/.zshrc and verify paths.

References