Documentation

Documentation

Welcome to the Æsh project documentation. Build powerful command-line applications in Java with minimal effort.

Choose Your Library

The Æsh project provides two libraries for different use cases:

Æsh - Command Framework (High-Level)

Build CLI applications with commands, options, and arguments

Æsh provides a high-level command framework with annotation-based definitions. Perfect for most CLI applications.

@CommandDefinition(name = "deploy", description = "Deploy application")
public class DeployCommand implements Command<CommandInvocation> {
    @Option(shortName = 'e')
    private String environment = "production";
    
    @Override
    public CommandResult execute(CommandInvocation invocation) {
        invocation.println("Deploying to " + environment);
        return CommandResult.SUCCESS;
    }
}

Use Æsh when:

  • Building CLI tools with commands and options
  • You want automatic parsing and validation
  • You need generated help text and tab completion
  • You prefer annotation-based development

→ Start with Æsh (Recommended for most users)

Æsh Readline - Terminal API (Low-Level)

Direct terminal control for custom applications

Æsh Readline provides bare-bones terminal input/output APIs. For advanced users who need fine-grained control.

Readline readline = ReadlineBuilder.builder().build();
readline.readline(connection, "prompt> ", input -> {
    // You handle parsing and logic
    connection.write("You entered: " + input + "\n");
});

Use Readline when:

  • Building custom terminal UIs or text-based games
  • You need low-level terminal event handling
  • Standard command patterns don’t fit your use case
  • You want maximum flexibility and control

→ Explore Readline (For advanced use cases)

Quick Start by Use Case

I’m building a CLI tool

→ Æsh Getting Started - Create commands with options and arguments

I need an interactive shell

→ Æsh Console Runner - Interactive shell with history and completion

I’m making a one-shot CLI utility

→ Æsh Runtime Runner - Single command execution from command line

I want to build a text-based game

→ Readline Terminal Control - Low-level terminal manipulation

I need remote terminal access (SSH/Telnet)

→ Readline Connectivity - Remote terminal servers

I want to see working examples

→ Æsh Examples | Readline Examples

Architecture Overview 

┌──────────────────────────────────────┐
│     Your CLI Application             │
└──────────┬───────────────────────────┘
           │
           ├─── Uses Æsh ───────────────────┐
           │    (High-level commands)       │
           │    • @CommandDefinition        │
           │    • Automatic parsing         │
           │    • Built-in help             │
           │    • Tab completion            │
           │                                │
           └─── Or Uses Readline ───────────┤
                (Low-level terminal)        │
                • readline()                │
                • Manual parsing            │
                • Terminal control          │
                • Event callbacks           │
                                            │
        ┌───────────────────────────────────┘
        │
        ▼
┌──────────────────────────────────────┐
│      Æsh Readline Core               │
│   (Terminal input/output layer)     │
└──────────┬───────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│   Terminal / Connection              │
│   (Local, SSH, Telnet, WebSocket)    │
└──────────────────────────────────────┘

Note: Æsh is built on top of Readline. You can use either:

  • Æsh for the full command framework (most users)
  • Readline directly for custom terminal applications (advanced users)

Documentation Structure

Æsh Documentation

Getting Started

Core Concepts

Advanced Features

Readline Documentation

Getting Started

Core API

Advanced Features

Resources

Examples Repository

All examples are available at github.com/aeshell/aesh-examples

  • Æsh console and runtime examples
  • Readline terminal examples
  • Remote connectivity examples
  • Full build instructions

Community

License

Æsh and Æsh Readline are licensed under the Apache License 2.0.