Moya commands are a way to write code that may be invoked from the command line. This allows you to write tools that you don't need (or want) to write an HTML user interface for. Commands also allow you to automate project actions with the standard tools your operating system provides.

Calling Commands ¶

You may already have used a command, if you have run through the tutorial. The following command line is an example of running a command in the auth application:

$ moya auth#cmd.init

If the first argument to the moya command contains a hash (#), moya treats it as an element reference, and runs the command associated with that element.

If you omit the text after the #, Moya will give you a table of the available commands. For example, run the following to list all the commands in the auth application:

$ moya auth#

If you add a -h switch after a command, Moya will show you the help text and options associated with the command. For example:

$ moya auth#cmd.listusers -h

Creating Commands ¶

To create a command, use the <command> tag. The libname is used to identify the command at the prompt, and the synopisis attribute is used when generating documentation. The code inside the <command> is run when the command is invoked. Here's an example of a very simple command:

<command libname="cmd.sayhello" synopsis="test command">
    <doc>Simple example of a command.</doc>
    <echo>Hello</Echo>
</command>

If the command above was in a library installed as example, you could run the command with the following:

$ moya example#cmd.sayhello

This should result in the text Hello being written to the terminal.

Code in a command has full access to the project environment, so you may query the database for example. You will be missing context values related to a request, such as .request itself, since no request is involved when running a command. Tags that depend on such context values may not work as expected.

Switches and Options ¶

You can add arguments and options to a command to create a more flexible command line interface. Let's add an argument to the example command which allows you to provide a name to greet:

<command libname="cmd.sayhello" synopsis="test command">
    <doc>Simple example of a command.</doc>
    <signature>
        <arg name="name" metavar="NAME" help="A name to greet" />
    </signature>
    <echo>Hello, ${args.name}!</Echo>
</command>

The <arg> tag adds a required argument to the command line. Here's how you cold invoke it:

$ moya example#cmd.sayhello John

When the above command line runs, Moya creates an object called args, containing arguments parsed from the command line. So args.name would be set to John, and you would see Hello, John! in the terminal.

You may add as many arguments as needed inside the <signature> tag. You can also add <option> tags which, as the name suggests, are optional. If you don't include an option, then the value in args will be set to a default value (if supplied) or to None.

Let's modify the example command to take an option:

<command libname="cmd.sayhello" synopsis="test command">
    <doc>Simple example of a command.</doc>
    <signature>
        <option name="name" metavar="NAME" help="A name to greet" default="User" />
    </signature>
    <echo>Hello, ${args.name}!</Echo>
</command>

You can now invoke the command with the following:

$ moya example#cmd.sayhello --name John

This will write the text Hello, John! to the console.

If you omit the option from the command line, then the args.name will contain the default value of User, and the command will write the text Hello, User! to the console. Most commands will use a combination of <arg> and <option> to create a fully featured command interface.