Factorial Docs

Appearance

CLI ​

  Table of Contents

The Factorial command-line interface, fctl, lets people and software agents read and modify Factorial records from a terminal. It also creates, uploads, and tests plugins.

Install FCTL ​

Open Plugins → Install FCTL in your Factorial environment, or visit /install/fctl on that environment's hostname. The page is public; no sign-in is required. It shows commands for macOS & Linux or Windows, selects the one that matches your browser, and fills in the download links for that environment's release.

macOS and Linux ​

Paste the command from the install page into Terminal. It has this form:

sh
os=$(uname -s | tr A-Z a-z); arch=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL -o fctl "https://downloads.factorialhq.com/fctl/<version>/$os/$arch/fctl"
sudo mkdir -p /usr/local/bin
sudo install -m 755 fctl /usr/local/bin/fctl && rm fctl

The command detects the operating system and processor, downloads the matching binary, and installs it in /usr/local/bin. sudo asks for your password.

Windows ​

Paste the command from the install page into PowerShell. It downloads the binary for your processor to %LOCALAPPDATA%\Factorial and adds that folder to your user Path. The current PowerShell window can run fctl immediately; other terminals pick up the new Path when reopened.

Manual Downloads ​

Under Download a binary instead, the install page lists every build: Apple silicon or x64 for macOS, and x64 or ARM64 for Linux and Windows. x64 covers Intel and AMD processors. The page also links to SHA-256 checksums. Each checksum entry identifies its operating system, architecture, and binary filename.

FCTL binaries are unsigned. macOS blocks unsigned binaries downloaded through a browser until you remove the quarantine flag:

sh
chmod +x fctl
sudo install -m 755 fctl /usr/local/bin/fctl
xattr -d com.apple.quarantine /usr/local/bin/fctl

Binaries downloaded with curl, as in the install command, do not receive the quarantine flag.

Connect to Factorial ​

FCTL reads FCTL_DOMAIN and FCTL_API_KEY from a .fctl file in your home directory, or from environment variables of the same names. Environment variables override the file. Use your Factorial hostname without https://.

Create a key on the API keys page of your Factorial environment. The Connect step of the install page shows a command that writes .fctl with that environment's hostname already filled in; replace <your-api-key> with the key. See Authenticate for the file format and API keys and service accounts for permissions.

Updates ​

Download FCTL from the environment you connect to so its version matches that server. Different environments can run different releases.

When a released CLI runs a command that connects to Factorial, it checks the server's version with a short timeout. A mismatch prints a warning and a download link to standard error. The warning does not change command output or exit status. If the check cannot complete, the command continues. Help and local commands do not check for updates; development builds skip the check.

To update, run the install command again. It replaces the installed binary with the release that matches the environment. Updates are manual.

Discovering Commands ​

Run fctl --help to list commands, or use --help with an individual command. Run fctl --version to see the installed revision. Some API endpoints do not have a corresponding CLI command.

AI Agents ​

Agents can inspect commands through --help and invoke the same CLI used by people. API key permissions apply to every request.