balena-cli/man/resin-plugins.1.md

resin-plugins(1) - Creating Resin CLI plugins

DESCRIPTION

Resin CLI plugins are managed by NPM. Installing an NPM module that starts with resin-plugin-* globally will automatically make it available to the Resin CLI.

TUTORIAL

In this guide, we'll create a simple hello plugin that greets the user.

Create a directory called resin-plugin-hello, containing a single index.js file.

Within the new project, run npm init and make sure the package name is set to resin-plugin-hello as well.

Also make sure that you have a main field in package.json that points to the index.js file you created above.

Your package.json should look something like this:

{
	"name": "resin-plugin-hello",
	"version": "1.0.0",
	"main": "index.js",
	"description": "My first Resin plugin",
	"license": "MIT"
}

Your index file should export an object (if exposing a single command) or an array of objects (if exposing multiple commands).

Notice that is very important that your package.json main field points to the file that is exporting the commands for the plugin to work correctly.

Each object describes a single command. The accepted fields are:

• signature: A Capitano signature.
• description: A string containing a short description of the command. This will be shown on the Resin general help.
• help: A string containing an usage help page. This will be shown when passing the signature to the help command.
• action: A function that defines the action to take when the command is matched. The function will be given 3 arguments (params, options, done).
• permission: A string describing the required permissions to run the command.
• options: An array of Capitano options.

The index.js file should look something like:

module.exports = [
	{
		signature: 'hello <name>',
		description: 'example plugin',
		help: 'This is an example plugin.',
		action: function(params, options, done) {
			console.log('Hey there ' + params.name + '!');
			done();
		}
	}
]

As we're only exporting a single command, we can export the object directly:

module.exports = {
	signature: 'hello <name>',
	description: 'example plugin',
	help: 'This is an example plugin',
	action: function(params, options, done) {
		console.log('Hey there ' + params.name + '!');
		done();
	}
}

This example will register a hello command which requires a name parameter, and greets the user in result.

To test the plugin, first create a global link by running the following command inside your plugin directory:

$ npm link

Now if you run $ resin help you should see your new command at the bottom of the list.

Try it out:

$ resin hello Juan
Hey there Juan!

DONE CALLBACK

It's very important that you call the done() callback after your action finishes. If you pass an Error instance to done(), its message will be displayed by the Resin CLI, exiting with an error code 1.

If your action is synchronous and doesn't return any error, you can omit the done() callback all together. For example:

module.exports = {
	signature: 'hello <name>',
	description: 'example plugin',
	help: 'This is an example plugin',
	action: function(params, options) {
		console.log('Hey there ' + params.name + '!');
	}
}

PERMISSIONS

You can set a command permission to restrict access to the commands. Currently, the only registered permission is user, which requires the user to log in to Resin from the CLI.

To require the user to login before calling our hello plugin, we can add permission: 'user' to the command description:

module.exports = {
	signature: 'hello <name>',
	description: 'example plugin',
	help: 'This is an example plugin',
	permission: 'user',
	action: function(params, options, done) {
		console.log('Hey there ' + params.name + '!');
		done();
	}
}

Now if the user attempts to call our command without being logged in, a nice error message asking him to login will be shown instead.

OPTIONS

You can define certain options that your command accepts. Notice these are per command, and thus are not available to other command that doesn't declares them as well.

Let's say we want to allow the user to configure the greeting language. For example:

$ resin hello Juan --language spanish

We first need to register the language option:

module.exports = {
	signature: 'hello <name>',
	description: 'example plugin',
	help: 'This is an example plugin',
	options: [
		{
			signature: 'language',
			parameter: 'language',
			description: 'the greeting language',
			alias: 'l'
		}
	],
	action: function(params, options, done) {
		if(options.language === 'spanish') {
			console.log('Hola ' + params.name + '!');
		} else {
			console.log('Hey there ' + params.name + '!');
		}

		done();
	}
}

Here, we declared an option with a signature of language (so we can use it as --language), a parameter name of language as well (this means we'll be able to access the option as the language key: options.language), a nice description and an alias l (which means we can use -l <language> too).

COFFEESCRIPT

We have CoffeeScript support out of the box. Implement your commands in index.coffee and point package.json main to that file.

RESIN-SDK

You can use the Resin SDK NodeJS module within your own plugins to communicate with Resin.

RESIN-CLI-VISUALS

Use the Resin CLI Visuals module to make use of the widgets used by the built-in CLI commands.