Using the CLI

The ashen CLI provides tools for interacting with the Ashen chain, managing contracts, and automating workflows.

Quick Start

# Check chain status
ashen status

# Query an account
ashen account --address 0x1234...

# Call a contract method (read-only)
ashen view 0xCONTRACT balanceOf '["0xUSER"]'

# Execute a transaction
ashen call 0xCONTRACT transfer '["0xTO", 100]' --key $KEY --wait

Environment Variables

Variable	Description
NODE_RPC_URL	RPC endpoint (default: http://127.0.0.1:3030)
NODE_AUTH_TOKEN	Optional authentication token
ASHEN_PRIVATE_KEY	Private key for signing transactions

---

Core Commands

ashen status

Get chain status including tip height, epoch, and finalized block.

ashen status
ashen status --rpc-url http://custom:3030

ashen account

Query account information including balance and nonce lanes.

ashen account --address 0x1234...

ashen view

Execute a read-only contract call (no transaction, no gas cost).

# Basic view call
ashen view 0xCONTRACT methodName '["arg1", "arg2"]'

# With explicit IDL path
ashen view 0xCONTRACT balanceOf '["0xUSER"]' --idl ./token.idl

# Multi-interface contract
ashen view 0xCONTRACT totalSupply --interface IERC20

IDLs are auto-fetched from the chain and cached for 1 hour. Use --idl to override.

ashen call

Execute a state-changing transaction.

# Basic call (simulates only)
ashen call 0xCONTRACT transfer '["0xTO", 100]' --key $KEY

# Submit and wait for inclusion
ashen call 0xCONTRACT transfer '["0xTO", 100]' --key $KEY --wait

# Custom gas/fee
ashen call 0xCONTRACT mint '["0xTO", 1000]' --key $KEY \
  --gas-limit 500000 --max-fee 2000000 --wait

ashen abi

Display a contract’s IDL/ABI.

# Pretty-printed
ashen abi 0xCONTRACT

# Raw IDL text
ashen abi 0xCONTRACT --raw

---

Contract Commands

ashen contract inspect

Inspect a local IDL file without connecting to the chain.

ashen contract inspect --idl ./mycontract.idl

ashen contract view

Detailed view call with more options.

ashen contract view \
  --contract 0x1234... \
  --method balanceOf \
  --args '["0xUSER"]' \
  --idl ./token.idl \
  --origin 0xCALLER

ashen contract call

Detailed call with simulation and submission options.

# Simulate only (default)
ashen contract call \
  --contract 0x1234... \
  --method transfer \
  --args '["0xTO", 100]' \
  --key $KEY

# Simulate and submit
ashen contract call ... --wait

# Force submit even on simulation failure
ashen contract call ... --force --wait

---

Transaction Commands

ashen tx by-hash

Query a transaction by its hash.

# Get status
ashen tx by-hash --tx-hash 0xABCD...

# Wait for inclusion
ashen tx by-hash --tx-hash 0xABCD... --wait --wait-timeout-s 120

---

IDL Commands

ashen idl fetch

Fetch a contract’s IDL from the chain.

ashen idl fetch --contract 0x1234...
ashen idl fetch --contract 0x1234... --output ./contract.idl

ashen idl generate

Generate a manifest from a local IDL file (selectors, methods, types).

ashen idl generate --idl ./mycontract.idl
ashen idl generate --idl ./mycontract.idl --output ./manifest.json

ashen idl validate

Validate IDL syntax and semantics.

ashen idl validate ./mycontract.idl

ashen idl diff

Compare two IDL versions and report breaking changes.

ashen idl diff old.idl new.idl
ashen idl diff old.idl new.idl --json

ashen idl codegen

Generate client code from an IDL file.

# TypeScript
ashen idl codegen ./token.idl --lang ts --output-dir ./generated

# Rust
ashen idl codegen ./token.idl --lang rust --output-dir ./generated

Supported languages: ts/typescript, rust, go, c

---

Keystore Commands

ashen keystore init

Initialize a new keystore.

ashen keystore init
ashen keystore init --path ~/.ashen/keystore.json

ashen keystore list

List keys in the keystore.

ashen keystore list

ashen keystore add

Add a new key.

# Generate new key
ashen keystore add --label my-key

# Import existing
ashen keystore add --label imported --secret 0x...

ashen keystore export

Export a key’s public address.

ashen keystore export --label my-key

---

Interactive TUI

Launch the interactive terminal UI for visual exploration.

# Launch TUI
ashen

# Or explicitly
ashen tui

The TUI provides:

• Block Explorer — Browse blocks and transactions
• Account Viewer — Check balances and nonces
• Contract Caller — Execute view and call operations
• Transaction History — Track your submitted transactions
• Favorites — Quick access to frequently used contract methods
• RPC Explorer — Dynamic RPC method discovery

TUI Screens

Screen	Key	Description
Home	h	Main menu
Block Explorer	b	Browse recent blocks
Account Viewer	a	Check account details
Contracts	c	Manage contract addresses
IDLs	i	Manage IDL files
Favorites	f	Quick access methods
Transaction History	t	Your submitted txs
Settings	s	Configure RPC, keys
Help	?	Keyboard shortcuts

TUI Configuration

Configuration is stored in ~/.config/ashen/config.toml:

rpc_url = "http://127.0.0.1:3030"
auth_token = ""
default_key = ""
block_buffer_limit = 100
tx_history_limit = 64

[idls]
sft = { path = "/path/to/sft.idl" }
amm = { path = "/path/to/amm.idl", namespace = "v1" }

[contracts]
token = "0x1234..."
pool = "0x5678..."

---

Robot Mode (Agent Automation)

The ashen tui subcommand provides headless commands with JSON output, designed for AI agents and automation.

How Robot Mode Works

• All ashen tui commands output JSON when:
  • --json flag is provided, OR
  • stdout is not a TTY (piped or redirected)
• Human-readable output when run interactively without --json

JSON Response Schema

Success:

{
  "ok": true,
  "data": { ... },
  "warnings": ["optional warning messages"]
}

Error:

{
  "ok": false,
  "code": "invalid_args",
  "message": "Description of what went wrong",
  "suggestions": ["possible fix 1", "possible fix 2"]
}

Exit Codes

Code	Meaning
0	Success
1	Not found
2	Invalid arguments
3	Authentication error
4	Conflict
5	Internal error

Robot Mode Commands

Chain Status

# Get chain status
ashen tui status --json
# Returns: tip_height, tip_hash, epoch, finalized_height, chain_id

# Get account info
ashen tui account 0x1234... --json
# Returns: address, balance, nonce_lanes, has_code

Contract Interaction

# View call (read-only)
ashen tui view --contract 0x... --method balanceOf --args '["0xUSER"]' --json

# Call with simulation only
ashen tui call --contract 0x... --method transfer \
  --args '["0xTO", 100]' --key $KEY --json

# Submit transaction
ashen tui call --contract 0x... --method transfer \
  --args '["0xTO", 100]' --key $KEY --submit --json

# Submit and wait for inclusion
ashen tui call --contract 0x... --method transfer \
  --args '["0xTO", 100]' --key $KEY --submit --wait --json

Transaction Operations

# Get transaction details
ashen tui tx details 0xHASH... --json

# Wait for tx inclusion
ashen tui tx wait 0xHASH... --timeout 120 --json

# List transactions (with filters)
ashen tui tx list --limit 50 --json
ashen tui tx list --sender 0x... --json
ashen tui tx list --contract 0x... --before 1000 --json

# Local tx history
ashen tui tx history --limit 20 --json

Block Operations

# List recent blocks
ashen tui blocks list --limit 20 --json
ashen tui blocks list --before 1000 --limit 50 --json

# Get block details
ashen tui blocks get 100 --json

Mempool

# List pending transactions
ashen tui mempool --limit 50 --json

Configuration Management

# Get/set config values
ashen tui config get rpc-url --json
ashen tui config set rpc-url http://node:3030 --json

# Manage IDLs
ashen tui config idls list --json
ashen tui config idls add --name sft --path ./sft.idl --json
ashen tui config idls remove sft --json

# Manage contracts
ashen tui config contracts list --json
ashen tui config contracts add --name token --address 0x... --json
ashen tui config contracts remove token --json

# Manage favorites
ashen tui config favorites list --json
ashen tui config favorites add --contract 0x... --idl sft --method mint --json
ashen tui config favorites remove 0 --json

Contract Methods Discovery

# List contract methods
ashen tui contract methods --contract 0x... --json
ashen tui contract methods --contract 0x... --idl ./custom.idl --json

Dynamic RPC

# List all RPC methods
ashen tui rpc methods --json

# Get method signature
ashen tui rpc method chain_status --json

# Execute RPC call
ashen tui rpc call chain_status --json
ashen tui rpc call account '{"address": "0x..."}' --json

Agent Workflow Example

#!/bin/bash
# Agent workflow: check balance, transfer, wait for confirmation

# 1. Check balance
BALANCE=$(ashen tui account 0xFROM... --json | jq -r '.data.balance')
echo "Current balance: $BALANCE"

# 2. Check if sufficient
if [ "$BALANCE" -lt 1000 ]; then
  echo "Insufficient balance"
  exit 1
fi

# 3. Execute transfer and wait
RESULT=$(ashen tui call \
  --contract 0xTOKEN... \
  --method transfer \
  --args '["0xTO...", 100]' \
  --key "$ASHEN_PRIVATE_KEY" \
  --submit --wait --json)

# 4. Check result
if echo "$RESULT" | jq -e '.ok' > /dev/null; then
  TX_HASH=$(echo "$RESULT" | jq -r '.data.tx_hash')
  echo "Transfer successful: $TX_HASH"
else
  ERROR=$(echo "$RESULT" | jq -r '.message')
  echo "Transfer failed: $ERROR"
  exit 1
fi

---

Debug Commands

ashen debug trace

Trace a transaction’s execution.

ashen debug trace --tx-hash 0x...

ashen debug replay

Replay a transaction with debugging.

ashen debug replay --tx-hash 0x... --breakpoint pc:0x1000

---

Backup Commands

ashen backup export

Export a chain snapshot.

ashen backup export --data-dir ./node-data --output ./snapshot.tar

ashen backup import

Import a chain snapshot.

ashen backup import --data-dir ./node-data --input ./snapshot.tar

---

BLS Commands (Validators)

ashen bls keygen

Generate a BLS keypair.

ashen bls keygen

ashen bls verify

Verify a BLS signature.

ashen bls verify --pubkey 0x... --message 0x... --signature 0x...