Interface Command

  • All Known Implementing Classes:
    AbstractCommand

    public interface Command
    Represents a single executable command in the shell.

    A Command encapsulates everything about a command in one object: its name, aliases, description, execution logic, and completion support.

    Example:

     Command echo = new AbstractCommand("echo") {
         @Override
         public Object execute(CommandSession session, String[] args) {
             session.out().println(String.join(" ", args));
             return null;
         }
     };
     
    Since:
    4.0
    See Also:
    CommandGroup, CommandDispatcher, CommandSession
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default java.util.List<java.lang.String> aliases()
      Returns alternative names for this command.
      default org.jline.reader.Completer completer()
      Returns a single completer for this command's arguments.
      default java.util.List<org.jline.reader.Completer> completers()
      Returns the completers for this command's arguments.
      default CommandDescription describe​(java.util.List<java.lang.String> args)
      Returns a detailed description of this command for the given arguments.
      default java.lang.String description()
      Returns a short, one-line description of this command.
      java.lang.Object execute​(CommandSession session, java.lang.String[] args)
      Executes this command with the given session and arguments.
      java.lang.String name()
      Returns the primary name of this command.
      default java.util.Map<java.lang.String,​Command> subcommands()
      Returns the subcommands of this command.
    • Method Detail

      • name

        java.lang.String name()
        Returns the primary name of this command.
        Returns:
        the command name, never null
      • aliases

        default java.util.List<java.lang.String> aliases()
        Returns alternative names for this command.

        The default implementation returns an empty list.

        Returns:
        the list of aliases, never null
      • description

        default java.lang.String description()
        Returns a short, one-line description of this command.

        Used for help listings and completion candidates.

        Returns:
        the description, or empty string if none
      • describe

        default CommandDescription describe​(java.util.List<java.lang.String> args)
        Returns a detailed description of this command for the given arguments.

        This is used by widgets to display context-sensitive help in the terminal status bar.

        Parameters:
        args - the command arguments (args[0] is typically the command name)
        Returns:
        the command description, or null if not available
      • execute

        java.lang.Object execute​(CommandSession session,
                                 java.lang.String[] args)
                          throws java.lang.Exception
        Executes this command with the given session and arguments.
        Parameters:
        session - the current command session
        args - the command arguments (does not include the command name)
        Returns:
        the result of the command execution, or null
        Throws:
        java.lang.Exception - if command execution fails
      • completers

        default java.util.List<org.jline.reader.Completer> completers()
        Returns the completers for this command's arguments.

        The default implementation returns an empty list, meaning no custom completion.

        These completers are position-based: the first completer handles the first argument, the second handles the second argument, etc. For commands that need non-positional completion (e.g., picocli commands where options can appear in any order), override completer() instead.

        Returns:
        the list of completers
        See Also:
        completer()
      • completer

        default org.jline.reader.Completer completer()
        Returns a single completer for this command's arguments.

        This method is called by the dispatcher to get the completer for this command. The default implementation builds a completer from completers().

        Override this method when position-based completion is not appropriate, for example with picocli commands where options and arguments can appear in any order.

        Returns:
        the completer, or null for no completion
        See Also:
        completers()
      • subcommands

        default java.util.Map<java.lang.String,​Command> subcommands()
        Returns the subcommands of this command.

        When a command has subcommands, the dispatcher will check if the first argument matches a subcommand name and route execution accordingly. For example, a "git" command with a "commit" subcommand would handle git commit -m msg by routing to the "commit" subcommand with args [-m, msg].

        The default implementation returns an empty map, meaning no subcommands.

        Returns:
        a map from subcommand name to command, never null