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_DOMAIN=kibble.factorialhq.com

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

Environment variables with the same names override the values in ~/.fctl. If both are set in the environment, the file is optional. Commands that change data, such as fctl plugins upload, print the target environment before sending.

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 configured credentials and uploads the plugin to the environment configured by FCTL_DOMAIN.