Factorial Docs

Appearance

Writing Your First Plugin ​

  Table of Contents

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 ​

Open Plugins → Install FCTL in your Factorial environment and download the binary for your operating system and processor. Follow the CLI installation instructions, then run fctl --version.

Authenticate ​

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

dotenv
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:

sh
fctl plugins 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. Give every hook, receiver, action, or job its own entrypoint file, even when two hooks run the same logic. See Sharing script logic for how to reuse helper functions, and Plugins for the available script types.

Upload the Plugin ​

Pass the plugin directory to fctl plugins upload:

sh
fctl plugins upload ./my-plugin

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

sh
fctl plugins upload

The CLI uses the configured credentials and uploads the plugin to the environment configured by FCTL_DOMAIN.