Interface Command
-
- All Known Implementing Classes:
AbstractCommand
public interface CommandRepresents a single executable command in the shell.A
Commandencapsulates 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 Completercompleter()Returns a single completer for this command's arguments.default java.util.List<Completer>completers()Returns the completers for this command's arguments.default CommandDescriptiondescribe(java.util.List<java.lang.String> args)Returns a detailed description of this command for the given arguments.default java.lang.Stringdescription()Returns a short, one-line description of this command.java.lang.Objectexecute(CommandSession session, java.lang.String[] args)Executes this command with the given session and arguments.java.lang.Stringname()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 sessionargs- 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<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 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 msgby 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
-
-