Interactive Console

An interactive REPL for Cardano development, prototyping, and debugging.

Overview

The Interactive Console provides:

• Quick prototyping without writing full scripts
• Live network interaction
• Built-in utility commands
• Command history
• Custom command support

Installation

import {
  startConsole,
  executeCommand,
  getCommands,
  createCustomConsole,
} from 'cardano-devkit';

Starting the Console

Basic Usage

// Start with default settings (Preprod)
await startConsole();

// With specific network
await startConsole({ network: 'Preview' });

// With custom configuration
await startConsole({
  network: 'Preprod',
  showBanner: true,
  maxHistory: 100,
});

CLI Usage

# Start interactive console
cardano-devkit console

# With network option
cardano-devkit console --network Preview

Built-in Commands

Command	Aliases	Description
help	?, h	Show available commands
network	net	Show or switch network
tip		Show current chain tip
balance	bal	Check address balance
convert	conv	Convert ADA/lovelace
validate	val	Validate address or tx hash
init		Initialize Lucid connection
clear	cls	Clear the console
history	hist	Show command history
exit	quit, q	Exit the console

Command Examples

Check Network

cardano:preprod> network
🌐 Current network: Preprod

cardano:preprod> network Preview
✅ Switched to Preview

Check Balance

cardano:preprod> balance addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer...

💰 Balance for addr_test1qz2fxv2u...
   ₳ 1,234.567890
   UTxOs: 5

Convert Values

cardano:preprod> convert 100 ada
💱 100 ADA = 100,000,000 lovelace

cardano:preprod> convert 5000000 lovelace
💱 5,000,000 lovelace = 5.0 ADA

Validate Addresses

cardano:preprod> validate addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer...
🔍 Address: ✅ Valid

cardano:preprod> validate abc123invalid
🔍 Address: ❌ Invalid

Validate Transaction Hashes

cardano:preprod> validate 8a4c3c7b8e9f1d2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b
🔍 Transaction Hash: ✅ Valid

Programmatic Execution

Execute commands programmatically without the interactive interface:

import { executeCommand } from 'cardano-devkit';

// Execute a single command
const result = await executeCommand('balance', ['addr_test1...'], {
  network: 'Preprod',
});

console.log(result);

Get Available Commands

import { getCommands } from 'cardano-devkit';

const commands = getCommands();
commands.forEach(cmd => {
  console.log(`${cmd.name}: ${cmd.description}`);
});

Custom Commands

Add your own commands to the console:

import { createCustomConsole } from 'cardano-devkit';

const customCommands = [
  {
    name: 'mybalance',
    aliases: ['mb'],
    description: 'Check my wallet balance',
    handler: async (args, ctx) => {
      // Your custom logic
      const address = 'addr_test1...'; // Your address
      const lucid = ctx.lucid;
      // ... check balance
      console.log('Your balance: ₳ 100');
    },
  },
  {
    name: 'faucet',
    description: 'Request funds from faucet',
    usage: 'faucet <address>',
    handler: async (args, ctx) => {
      if (args.length === 0) {
        console.log('Usage: faucet <address>');
        return;
      }
      // Request from faucet...
      console.log('Funds requested!');
    },
  },
];

const console = createCustomConsole(customCommands, {
  network: 'Preprod',
});

await console.start();

Console Context

Commands receive a context object with:

interface ConsoleContext {
  // DevKit instance
  devKit: CardanoDevKit;

  // Lucid instance (after init)
  lucid: Lucid | null;

  // Current network
  network: NetworkType;

  // Helper functions
  helpers: {
    adaToLovelace: (ada: number) => bigint;
    lovelaceToAda: (lovelace: bigint) => number;
    formatAda: (lovelace: bigint) => string;
    validateAddress: (addr: string) => boolean;
    validateTxHash: (hash: string) => boolean;
  };

  // Command history
  history: string[];
}

Configuration

interface ConsoleConfig {
  // Network to connect to
  network?: NetworkType;

  // Custom provider URL
  providerUrl?: string;

  // Show welcome banner (default: true)
  showBanner?: boolean;

  // History file path
  historyFile?: string;

  // Maximum history entries (default: 100)
  maxHistory?: number;
}

Tips

1. Initialize Lucid first - Run init before commands that need Lucid
2. Use aliases - bal instead of balance, net instead of network
3. Tab completion - Arrow keys navigate command history
4. Ctrl+C - Cancel current input, Ctrl+D exits

Integration with DevKit

The console uses DevKit internally, so all DevKit features are available:

// In a custom command handler
handler: async (args, ctx) => {
  // Switch networks
  await ctx.devKit.switchNetwork('Preview');

  // Get Lucid instance
  const lucid = ctx.devKit.getLucid();

  // Access current network
  console.log('Network:', ctx.devKit.getNetwork());
}