# How the Interactive Shell Feature Works in Embabel Agent

> Explore the interactive shell feature in Embabel Agent. Learn how this Spring Shell REPL console enables command execution directly from your prompt without a web server.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: internals
- Published: 2026-08-09

---

**Embabel Agent's interactive shell feature provides a Spring Shell-based REPL console that activates when configured via [`application-shell.yml`](https://github.com/embabel/embabel-agent/blob/main/application-shell.yml), allowing developers to execute agent commands from a command prompt without starting a web server.**

The Embabel Agent framework includes a built-in interactive shell feature that transforms your agent application into a command-line REPL environment. Powered by Spring Shell, this capability enables developers to interact with agent logic directly from the terminal using custom commands. When activated through specific configuration properties in the `embabel.agent.shell.*` namespace, the shell bypasses the traditional web server startup and presents an interactive prompt for real-time agent execution.

## Core Architecture Components

The interactive shell feature relies on four key components that orchestrate the transition from a standard Spring Boot application to an interactive command environment.

### AgentShellProperties

**`AgentShellProperties`** serves as the configuration holder for all shell-related settings. Located in the auto-configuration module, this class binds properties prefixed with `embabel.agent.shell.*` from the environment. It defines flags for exit commands, quit commands, interactive mode, history settings, and critically sets `web-application-type=none` to prevent embedded server startup.

### ShellEnvironmentPostProcessor

**`ShellEnvironmentPostProcessor`** implements Spring Boot’s `EnvironmentPostProcessor` interface to inject shell settings before the application context refreshes. According to the Embabel source code, this processor reads the `AgentShellProperties` and constructs a high-priority `MapPropertySource` named **`shellModeProperties`**. This property source translates Embabel-specific flags into Spring Shell properties such as `spring.shell.command.exit.enabled` and `spring.shell.interactive.enabled`, ensuring the shell beans receive correct configuration during initialization.

### AgentShellAutoConfiguration

**`AgentShellAutoConfiguration`** provides the Spring Boot auto-configuration that registers shell components when shell mode is detected. This configuration class uses `@ComponentScan(basePackages = "com.embabel.agent.shell")` to discover command classes and instantiates the core `Shell` bean along with prompt providers and collaborators required for the REPL interface.

### Spring Shell Integration

**Spring Shell** (via the `spring-shell` dependency) supplies the actual REPL implementation, including command parsing, prompt display, history management, and termination logic. The `Shell` bean reads the properties injected by `ShellEnvironmentPostProcessor` and initiates a prompt loop when `spring.shell.interactive.enabled` evaluates to `true`. Commands annotated with `@ShellComponent` within the `com.embabel.agent.shell` package become available at the prompt.

## Configuration and Startup Flow

Activating the interactive shell feature requires a specific YAML configuration profile and follows a precise initialization sequence.

### Enabling Shell Mode

Create an [`application-shell.yml`](https://github.com/embabel/embabel-agent/blob/main/application-shell.yml) file in your resources directory with the following structure:

```yaml
embabel:
  agent:
    shell:
      web-application-type: none          # Prevents web server startup

      command:
        exit-enabled: true                # Enables `exit` command

        quit-enabled: true                # Enables `quit` command

      interactive:
        enabled: true                     # Activates the REPL prompt

```

### Initialization Sequence

When the application boots with this configuration:

1. **`ShellEnvironmentPostProcessor`** executes early in the lifecycle, adding the `shellModeProperties` source to the environment
2. **`AgentShellAutoConfiguration`** detects `embabel.agent.shell.interactive.enabled=true` and registers Spring Shell beans
3. The **`Shell`** bean initializes, displaying a prompt (provided by a `PromptProvider` implementation) and awaiting input
4. User input routes to **`@ShellComponent`** methods located in the `com.embabel.agent.shell` package
5. Termination commands respect the `exit-enabled` and `quit-enabled` properties, shutting down the JVM when invoked

### Starting the Application

Run your agent with the shell configuration using Maven:

```bash
mvn spring-boot:run -Dspring.config.location=classpath:/application-shell.yml

```

Or execute the packaged JAR:

```bash
java -jar my-agent-app.jar --spring.config.location=classpath:/application-shell.yml

```

Upon successful startup, you will see the Embabel prompt:

```

embabel>

```

## Creating Custom Shell Commands

Developers extend the interactive shell by creating Spring Shell commands in the scanned package. The following example demonstrates a custom command that delegates to agent functionality:

```java
package com.embabel.agent.shell;

import org.springframework.shell.standard.ShellComponent;
import org.springframework.shell.standard.ShellMethod;

@ShellComponent
public class AgentExecutionCommands {

    @ShellMethod(key = "run", value = "Execute the agent with provided input")
    public String runAgent(String input) {
        // Delegate to your Embabel agent business logic
        return AgentService.process(input);
    }
    
    @ShellMethod(key = "status", value = "Display current agent status")
    public String showStatus() {
        return AgentService.getCurrentStatus();
    }
}

```

Commands defined with `@ShellMethod` automatically appear in the shell's help system and become accessible at the `embabel>` prompt.

## Non-Interactive Batch Mode

The interactive shell feature supports headless execution by disabling the REPL. Set `interactive.enabled` to `false` in your configuration:

```yaml
embabel:
  agent:
    shell:
      interactive:
        enabled: false

```

In this mode, the application runs without displaying a prompt, executing any specified commands immediately and terminating upon completion. This configuration suits CI/CD pipelines and scheduled tasks that require shell command parsing without human interaction.

## Summary

- **Embabel Agent** leverages Spring Shell to provide a REPL environment through the `embabel.agent.shell.*` property namespace
- **`ShellEnvironmentPostProcessor`** injects configuration early by creating a high-priority `MapPropertySource` named `shellModeProperties`
- **`AgentShellAutoConfiguration`** scans the `com.embabel.agent.shell` package to register commands and the `Shell` bean when interactive mode is enabled
- **[`application-shell.yml`](https://github.com/embabel/embabel-agent/blob/main/application-shell.yml)** configures the feature by setting `web-application-type=none` and `interactive.enabled=true`
- Custom commands use the **`@ShellComponent`** and **`@ShellMethod`** annotations to expose agent functionality at the command prompt
- The feature supports both interactive REPL mode and non-interactive batch execution via configuration flags

## Frequently Asked Questions

### How do I enable the interactive shell feature in Embabel Agent?

Enable the feature by creating an [`application-shell.yml`](https://github.com/embabel/embabel-agent/blob/main/application-shell.yml) file with `embabel.agent.shell.interactive.enabled=true` and `web-application-type=none`, then start the application with `--spring.config.location=classpath:/application-shell.yml`. This configuration prevents the web server from starting and initializes the Spring Shell REPL instead.

### What controls the exit and quit commands in the shell?

The **`AgentShellProperties`** class defines `exit-enabled` and `quit-enabled` flags under `embabel.agent.shell.command.*`. These properties map to Spring Shell's `spring.shell.command.exit.enabled` and `spring.shell.command.quit.enabled` settings via the **`ShellEnvironmentPostProcessor`**, determining whether typing `exit` or `quit` terminates the application.

### Can I run Embabel Agent in shell mode without the interactive prompt?

Yes. Set `embabel.agent.shell.interactive.enabled=false` in your configuration to run in batch mode. This configuration parses and executes commands without displaying the REPL prompt, suitable for automated scripts and headless environments.

### Where should I place my custom shell command classes?

Place **`@ShellComponent`** classes in the `com.embabel.agent.shell` package or its subpackages. The **`AgentShellAutoConfiguration`** automatically scans this base package during startup, registering any discovered commands with the Spring Shell infrastructure.