In two short steps, you can have a new plugin-project up and running; this can be done using Forge itself!

That's it! Now your project is ready to be compiled and installed in Forge, but you may still want to add some commands.

If you do not wish to create a new plugin project using Forge itself, you will need to manually include the Forge-API dependencies. For purposes of simplicity, we have pasted a sample Maven POM file which can be used as a starting point for a new plugin:

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                             http://maven.apache.org/xsd/maven-4.0.0.xsd" 
    xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.plugin</groupId>
  <artifactId>example</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <properties>
    <forge.api.version>[1.0.0-SNAPSHOT,)</forge.api.version>
  </properties>
  
  <dependencies>
    <dependency>
      <groupId>org.jboss.seam.forge</groupId>
      <artifactId>forge-shell-api</artifactId>
      <version>${forge.api.version}</version>
    </dependency>
  </dependencies>
  
  <repositories>
    <repository>
      <id>jboss</id>
      <url>https://repository.jboss.org/nexus/content/groups/public/</url>
    </repository>
  </repositories>
  
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Default commands must be annotated with @DefaultCommand, and are not named; you may still provide help text or command metadata. Each plugin may have only one @DefaultCommand.

The following default command would be executed by executing the plugin by its name:

public class ExamplePlugin implements Plugin {
   @DefaultCommand
   public void exampleDefaultCommand( @Option String opt ) {
      // this method will be invoked, and 'opt' will be passed from the command line
   }
}

$ exampleplugin some-input

In this case, the value of 'opt' will be "some-input". @Options are described in detail later in this section.

Named commands must, to little surprise, be given a name with which they are invoked. This is done by placing the @Command(name="...") annotation on a public Java method in your Plugin class.

The following command would be executed by executing the plugin by its name, followed by the name of the command:

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( @Option(required=false) String opt, PipeOut out) {
       out.println(">> the command \"perform\" was invoked with the value: " + opt);
   }
}

$ exampleplugin perform
>> the command "perform" was invoked with the value: null

Notice that our command method has a parameter called "PipeOut," in addition to our 'opt' parameter. PipeOut is a special parameter, which can be placed in any order. It provides access to a variety of shell output functions, including enabling color and controlling piping between plugins.

Along with PipeOut, there is also a @PipeIn InputStream stream annotation, which is used to inject a piped input stream (output from another Plugin's PipeOut.) These concepts will be described more in the section on piping, but for now, you should just know that PipeOut is used to write output to the Forge console.

As mentioned above, options can be given both a long-name and/or a short-name. in which case, they would be defined like this:

@Option(name="one", shortName="o")

Short named parameters are called using a single dash '-' followed by the letter assigned '-o'; whereas long-named parameters are called using a double dash '--' immediately followed by the name '--one'. )

For example, the following command accepts several options, named 'one', and 'two':

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( 
                  @Option(name="one", shortName="o") String one,
                  @Option(name="two") String two,
                  PipeOut out) {
       out.println(">> option one equals: " + one);
       out.println(">> option two equals: " + two);
   }
}

The above command, when executed, would produce the following output:

$ example-plugin perform --one cat --two dog 
>> option one equals: cat
>> option two equals: dog

$ example-plugin perform --one cat --two dog
$ example-plugin perform --two dog --one cat
$ example-plugin perform --two dog -o cat

In addition to --named option parameters, as described above, parameters may also be passed on the command line by the order in which they are entered. These are called "ordered option parameters", and do not require any parameters other than help or description information.

@Option String value

The order of the options in the method signature controls how values are assigned from parsed Forge shell command statements.

For example, the following command accepts several options, named 'one', and 'two':

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( 
                  @Option String one,
                  @Option String two,
                  PipeOut out) {
       out.println(">> first option equals: " + one);
       out.println(">> second option equals: " + two);
   }
}

The above command, when executed, would produce the following output:

$ example-plugin cat dog 
>> option one equals: cat
>> option two equals: dog

Both --named and ordered option parameters can be mixed in the same command; there are some constraints on how commands must be typed, but there is a great deal of flexibility as well.

@Option String value,
@Option(name="num") int number

The order of ordered options in the method signature controls how values are assigned from the command line shell, whereas the named options have no bearing on the order in which inputs are provided on the command line.

For example, the following command accepts several options, named 'one', 'two', and several more options that are not named:

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( 
                  @Option(name="one") String one,
                  @Option(name="two") String two,
                  @Option String three,
                  @Option String four,
                  PipeOut out) {
       out.println(">> first option equals: " + one);
       out.println(">> second option equals: " + two);
       out.println(">> third option equals: " + three);
       out.println(">> fourth option equals: " + four);
   }
}

The above command, when executed, would produce the following output:

$ example-plugin --one cat --two dog bird lizard  
>> option one equals: cat
>> option two equals: dog 
>> option one equals: bird
>> option two equals: lizard

However, we could also achieve the same result by re-arranging parameters, and as long as the name-value pairs remain together, and the ordered values are passed in the correct order, interpretation will remain the same:

$ example-plugin --two dog bird --one cat lizard  
>> option one equals: cat
>> option two equals: dog 
>> option one equals: bird
>> option two equals: lizard

This table describes all of the available @Option(...) attributes and their usage.

@Option(name="exampleName")

@Option(required="false")