The Mozcmd Format
The mozcmd format is a way to store GCLI commands for easy access. It is available to Firefox users by setting the devtools.commands.dir to point to a directory containing a number of files with the extension mozcmd.
For example if you set devtools.commands.dir to point to C:\mozcmd (on windows or /Users/me/mozcmd on Mac/Unix), then Firefox will read mozcmd files from that directory when Firefox starts or when you run cmd refresh to reload them.
Syntax
The mozcmd file format is based on JSON, but with the ability to insert functions in key places - For example the exec function.
The root of the document is an Array, which contains a number of command objects suitable to be passed to gcli.addCommand().
An Example mozcmd File
The following example is taken from the demo repository.
[
{
name: 'hello',
description: 'Show a message',
params: [
{
name: 'name',
type: 'string',
description: 'Who to say hello to',
}
],
exec: function(args, context) {
return 'Good evening, ' + args.name;
}
}
]
Several commands can be placed in one file, and commands always take their name from the `name` property rather than the name of the file.
Comments are not allowed except inside functions.
When a command is executed, this will be set to that of the parent object, so this.name is the name of the command. If a setup step is required then it should be done on first execution, and any results cached on this.
Security
The idea is to provide the user with the security that just having a mozcmd file available to Firefox is not a security risk, they need to access the command before any JavaScript is executed.
(Note 'access' does not imply that a command needs to be executed. Commands can provide functions to customize parameters. 'Access' is defined as typing the name of the command on the command line (regardless of whether RETURN is pressed)
The current implementation of mozcmd simply evals the script in a Sandbox. This does not provide the promised level of protection, however Bug 767912 calls for the parser to be upgraded.
Further Documentation
See documentation about writing commands.
Extending the mozcmd Format
The mozcmd format is designed to be extensible to support registering Types and Fields. This feature is not enabled yet, however you can find how how it is designed to work.