Writing Your First Plugin

  Table of Contents

• Install the CLI
• Authenticate
• Create a Plugin Template
• Upload the Plugin

A Factorial plugin is a local directory containing a plugin manifest and its scripts. Use the Factorial command-line interface (CLI), fctl, to create the directory from a template and upload it to your Factorial environment.

Install the CLI

Install fctl before continuing.

Authenticate

Create a .fctl file in your home directory. Add the API key and Factorial environment domain:

FCTL_API_KEY=<your-api-key>
FCTL_ENV=kibble.factorialhq.com

FCTL_API_KEY is the API key used to authenticate CLI requests. FCTL_ENV is the domain of the Factorial environment that receives the plugin. Do not include https:// in the domain.

Keep .fctl out of source control because it contains a secret. The API key determines what the CLI can access, so use a key with only the permissions required to manage plugins. See API keys and service accounts for key-management guidance.

Create a Plugin Template

From the directory where you want to create the plugin, run:

fctl plugin init

This command creates a template containing the files needed for a plugin. Edit the manifest and scripts for the workflow you want to automate. See Plugins for the available script types and their behavior.

Upload the Plugin

Pass the plugin directory to fctl plugins upload:

fctl plugins upload ./my-plugin

If the current working directory is the plugin directory, omit the argument:

fctl plugins upload

The CLI uses the credentials in ~/.fctl and uploads the plugin to the environment configured by FCTL_ENV.