Shelter CLI

TypeScript command-line interface for interacting with Shelter from your terminal.

Quick start

Install and run packaged CLI globally

npm install shelter-messenger-cli -g 
shelter-messenger --key <0xPRIVATE_KEY> --nickname <nick> --contract <0xCONTRACT> --rpc <RPC_URL>

Install and run the development CLI

cd src/shelter-messenger-cli
npm install
npm run start -- --key <0xPRIVATE_KEY> --nickname <nick> --contract <0xCONTRACT> --rpc <RPC_URL>

Run the compiled CLI:

npm run build
node dist/index.js --key <…> --nickname <…> --contract <…> --rpc <…>

Flags:

• --chain-id — chain id (defaults to 31337).
• --log-level — debug, info, warn, error or none.
• --gas-price — gas price for legacy transactions (in wei or with gwei/ether suffix).
• --max-fee — max fee per gas for EIP-1559 transactions (in wei or with gwei/ether suffix).
• --max-priority-fee — max priority fee per gas for EIP-1559 transactions (in wei or with gwei/ether suffix).

The CLI persists chat state under ~/.shelter/states/<chain>-<contract>-<nick>.json using FileApplicationStateStorage.

The CLI runs an interactive readline shell with commands such as help, chat, topic, more <index>, topic-create, invite, send, topic-send and others. The vibe command prints a short friendly message.

Example

Alice and Bob from tests can be started like this:

npm run start -- --key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
--nickname alice --contract 0x5FbDB2315678afecb367f032d93F642f64180aa3 \
--rpc http://127.0.0.1:8545 --chain-id 31337

And

npm run start -- --key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d \
--nickname bob --contract 0x5FbDB2315678afecb367f032d93F642f64180aa3 \
--rpc http://127.0.0.1:8545 --chain-id 31337

Gas Configuration

Shelter supports flexible gas parameter configuration to control transaction speed and cost.

Transaction Types

Legacy Transactions (Pre-EIP-1559)

Use fixed gas price (gasPrice). Suitable for networks that don't support EIP-1559.

CLI Example:

# With gwei suffix
shelter --key 0x... --nickname alice --contract 0x... --rpc https://rpc.url --gas-price 50gwei

# In wei
shelter --key 0x... --nickname alice --contract 0x... --rpc https://rpc.url --gas-price 50000000000

EIP-1559 Transactions (Modern)

Use maxFeePerGas and maxPriorityFeePerGas for more flexible fee management.

CLI Example:

shelter --key 0x... --nickname alice --contract 0x... --rpc https://rpc.url \
  --max-fee 100gwei \
  --max-priority-fee 2gwei

Value Formats

CLI supports multiple formats for gas values:

• Wei (base unit): 50000000000
• Gwei (with suffix): 50gwei
• Ether (with suffix): 0.00005ether

Parameter Priority

Gas parameters are applied in the following priority order:

1. Transaction level - parameters passed directly to sendTransaction()
2. Configuration level - parameters from CLI flags or config file
3. Network defaults - if nothing is specified, network values are used

Validation Rules

• Cannot use both --gas-price (legacy) and EIP-1559 options (--max-fee, --max-priority-fee) simultaneously
• Both EIP-1559 parameters must be provided together
• All values must be positive numbers

Usage Examples

Fast Transaction (High Priority)

# Legacy
shelter ... --gas-price 100gwei

# EIP-1559
shelter ... --max-fee 150gwei --max-priority-fee 5gwei

Economical Transaction (Low Priority)

# Legacy
shelter ... --gas-price 20gwei

# EIP-1559
shelter ... --max-fee 30gwei --max-priority-fee 1gwei

Default Network Values

# Library automatically fetches current network gas prices
shelter --key 0x... --nickname alice --contract 0x... --rpc https://rpc.url

Programmatic Usage

For library users, gas configuration can be set via IBlockchainConfig:

import { StaticConfigProvider, EthereumProviderFactory } from 'shelter-client-library-std';

// Legacy transactions
const legacyConfig: IProviderConfig = {
    blockchain: {
        chainId: 1,
        rpcUrl: "https://ethereum-rpc.publicnode.com",
        name: "mainnet",
        customGasPrice: 50_000_000_000n, // 50 gwei in wei
        maxTrnRetry: 3
    },
    polling: { /* ... */ },
    crypto: { encryptionAlgorithm: "ecies" },
    contractAddress: "0x..."
};

// EIP-1559 transactions
const eip1559Config: IProviderConfig = {
    blockchain: {
        chainId: 1,
        rpcUrl: "https://ethereum-rpc.publicnode.com",
        name: "mainnet",
        maxFeePerGas: 100_000_000_000n,        // 100 gwei
        maxPriorityFeePerGas: 2_000_000_000n,  // 2 gwei (tip)
        maxTrnRetry: 3
    },
    polling: { /* ... */ },
    crypto: { encryptionAlgorithm: "ecies" },
    contractAddress: "0x..."
};

const configProvider = new StaticConfigProvider(eip1559Config, userConfig);
const providerFactory = new EthereumProviderFactory();
const provider = providerFactory.create(configProvider);

JSON Configuration

Gas parameters can also be specified in JSON config files:

{
  "blockchain": {
    "chainId": 1,
    "name": "mainnet",
    "rpcUrl": "https://ethereum-rpc.publicnode.com",
    "maxFeePerGas": "100000000000",
    "maxPriorityFeePerGas": "2000000000"
  },
  "polling": {
    "activeInterval": 5000,
    "backgroundInterval": 30000,
    "idleInterval": 60000,
    "batchSize": 100,
    "maxTopicBatchSize": 50
  },
  "crypto": {
    "encryptionAlgorithm": "ecies"
  },
  "contractAddress": "0x..."
}

Recommendations

1. For production: Use EIP-1559 on supporting networks (Ethereum, Polygon, etc.)
2. For testing: Network defaults are usually sufficient
3. During network congestion: Increase maxFeePerGas with safety margin
4. For urgent transactions: Increase maxPriorityFeePerGas to incentivize miners

Troubleshooting

Error: "Cannot use both customGasPrice and EIP-1559 parameters"

Use only one type of gas parameters - either legacy (--gas-price) or EIP-1559 (--max-fee and --max-priority-fee).

Error: "Both maxFeePerGas and maxPriorityFeePerGas must be provided together"

When using EIP-1559, both parameters are required.

Transaction not confirming

• Increase --gas-price (legacy) or --max-fee (EIP-1559)
• Check current network gas prices using block explorers
• Ensure values are in wei, not gwei (unless using suffix)