VOOZH about

URL: https://aeshell.github.io

⇱ Æsh, Another Extensible SHell

Æsh - Java Libraries for Command-Line Interfaces

Æsh (Another Extendable SHell) is a collection of Java libraries for building command-line interfaces, interactive shells, and terminal applications.

Overview

The Æsh project provides two complementary libraries:

  • Æsh - High-level command framework with annotation-based definitions
  • Æsh Readline - Low-level terminal input/output and line editing

Both libraries are production-ready, cross-platform (POSIX and Windows), and actively maintained.

Æsh - Command Framework

Æsh provides a high-level API for building CLI applications with commands, options, and arguments. It handles parsing, validation, type conversion, and help generation automatically.

Example 

@CommandDefinition(name="deploy",description="Deploy an application")publicclass DeployCommandimplementsCommand<CommandInvocation>{@Option(shortName='e',defaultValue="production",description="Target environment")privateStringenvironment;@Option(shortName='f',hasValue=false,description="Force deployment")privatebooleanforce;@Argument(description="Application name",required=true)privateStringapplication;@OverridepublicCommandResultexecute(CommandInvocationinvocation){invocation.println("Deploying "+application+" to "+environment);if(force){invocation.println("Force flag enabled");}returnCommandResult.SUCCESS;}}

Start an interactive console or execute single commands:

// Interactive console with history and tab completionAeshConsoleRunner.builder().command(DeployCommand.class).prompt("[deploy-tool]$ ").start();// Single command execution (for CLI tools)AeshRuntimeRunner.builder().command(DeployCommand.class).args(args).execute();

Key Capabilities

Command Definition

  • Annotation-based (@CommandDefinition, @Option, @Argument) or builder API
  • Automatic parsing and type conversion (String, Integer, Boolean, File, Enum, custom types)
  • Support for short (-v) and long (--verbose) option names
  • Required and optional parameters with default values

Command Organization

  • Command groups and subcommands (e.g., git remote add, docker container start)
  • Unlimited nesting depth for complex hierarchies
  • Dynamic command registration and removal at runtime

User Experience

  • Automatic help generation (--help)
  • Tab completion for commands, options, and values
  • Built-in completers for files, booleans, enums
  • Command history and line editing (via Readline)
  • Clear error messages and validation feedback

Extensibility

  • Validators - Custom validation rules for options and arguments
  • Converters - Convert string input to custom types
  • Completers - Domain-specific tab completion
  • Activators - Conditionally enable/disable options based on other options
  • Renderers - Customize help output format

Execution Modes

  • Console mode - Interactive shell with readline features
  • Runtime mode - Single command execution from command-line arguments
  • Programmatic - Direct command invocation from Java code

Use Cases

  • CLI tools and utilities
  • Interactive shells and REPLs
  • Build systems and deployment tools
  • System administration utilities
  • Developer tools and code generators

Æsh Readline - Terminal API

Æsh Readline provides low-level terminal input handling with GNU Readline compatibility. It’s used by Æsh internally but can be used standalone for custom terminal applications.

Example 

TerminalConnectionconnection=newTerminalConnection();Readlinereadline=ReadlineBuilder.builder().history(newFileHistory(newFile(".history"),100)).build();read(connection,readline);connection.openBlocking();privatestaticvoidread(TerminalConnectionconnection,Readlinereadline){readline.readline(connection,"prompt> ",input->{if(input!=null&&input.equals("exit")){connection.close();}else{connection.write("Echo: "+input+"\n");read(connection,readline);}});}

Key Capabilities

Line Editing

  • Full line editing with undo/redo support
  • Emacs and Vi editing modes
  • Customizable key bindings
  • Copy/paste with paste buffer

History Management

  • Persistent history with file storage
  • History search (Ctrl+R)
  • Configurable history size
  • Per-session or global history

Input Features

  • Tab completion with custom completers
  • Password masking for sensitive input
  • Multi-line input support
  • Prompt customization

Terminal Control

  • Cursor positioning and movement
  • Screen clearing and manipulation
  • Color and formatting (ANSI escape sequences)
  • Terminal size detection

Remote Connectivity

  • SSH server support (via terminal-ssh)
  • Telnet server support (via terminal-telnet)
  • WebSocket server support (via terminal-http)
  • Unified API for local and remote terminals

Platform Support

  • POSIX systems (Linux, macOS, BSD)
  • Windows (native and WSL)
  • Remote terminals via SSH/Telnet/WebSocket

Use Cases

  • Custom terminal applications and text-based UIs
  • Text editors and viewers
  • Terminal multiplexers
  • Interactive shells with custom syntax
  • Terminal-based games and animations
  • Remote shell applications

Architecture 

┌──────────────────────────────────────────────┐
│ Your Application │
└──────────────┬───────────────────────────────┘
 │
 ├─── Uses Æsh Framework ──────────┐
 │ • Command definitions │
 │ • Automatic parsing │
 │ • Validation & conversion │
 │ • Help generation │
 │ │
 └─── Or Uses Readline Directly ───┤
 • Terminal input/output │
 • Manual command handling │
 • Custom UI control │
 │
 ┌────────────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────┐
│ Æsh Readline (Core Library) │
│ • Terminal abstraction │
│ • Line editing & history │
│ • Completion & key bindings │
│ • Connection management │
└──────────────┬───────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────┐
│ Terminal / Connection Layer │
│ • Local TTY (POSIX/Windows) │
│ • SSH connections │
│ • Telnet connections │
│ • WebSocket connections │
└──────────────────────────────────────────────┘

Note: Æsh is built on top of Readline. Most users building CLI applications should use Æsh. Use Readline directly only when you need low-level terminal control.

Installation

Maven

Æsh (Command Framework):

<dependency>
 <groupId>org.aesh</groupId>
 <artifactId>aesh</artifactId>
 <version>1.7</version>
</dependency>

Æsh Readline (Terminal API):

<dependency>
 <groupId>org.aesh</groupId>
 <artifactId>readline</artifactId>
 <version>2.6</version>
</dependency>

Gradle

Æsh:

implementation 'org.aesh:aesh:1.7'

Readline:

implementation 'org.aesh:readline:2.6'

Extensions (Optional - Ready-made commands):

implementation 'org.aesh:aesh-extensions:1.7'

Documentation

Requirements

  • Java 8 or later
  • No external dependencies (beyond JDK)

Project Resources

License

Apache License 2.0

Related Projects

Æsh has been used in several open-source projects:

  • WildFly - Application server CLI
  • JBoss Tools - Command-line interfaces
  • Various system administration and developer tools

See the GitHub repository for more information.