Skip to content
Prefactor Prefactor Prefactor Docs

CLI configuration

This page covers the config file, environment variables, and input conventions for the Prefactor CLI.

Config file

Section titled “Config file”

The CLI stores profiles in a prefactor.json file. Each top-level key is a profile name, and each profile has a single api_key field containing the API token for that profile.

{
  "default": {
    "api_key": "pf_..."
  }
}

Resolution order

Section titled “Resolution order”

The CLI checks these locations in order and uses the first file it finds:

  1. <repo-root>/prefactor.json — the CLI walks up from the current directory to find the git or worktree root
  2. <executable-root>/prefactor.json — next to the installed binary

If neither exists, creating a profile writes <executable-root>/prefactor.json.

Environment variables

Section titled “Environment variables”

If no matching profile is found, the CLI falls back to PREFACTOR_API_TOKEN. This is useful in CI or for short-lived runs where creating a config file is impractical. For day-to-day use, named profiles are more predictable.

To select a profile by name without using the --profile flag, set PREFACTOR_PROFILE=<name>.

A profile authenticated with an account-level token has the same access scope as that token. Prefer deployment-scoped tokens when your CLI operations are limited to a single agent.

Security

Section titled “Security”

prefactor.json stores API tokens. Do not commit it to source control.

The CLI attempts to add prefactor.json to .gitignore automatically when the config is local and the current directory is a git repository. Verify this manually in monorepos or with non-standard git setups:

Terminal window
git check-ignore prefactor.json
git status --short

JSON input from files

Section titled “JSON input from files”

Commands that accept JSON payloads also accept a file path prefixed with @:

Terminal window
prefactor bulk execute --items @./bulk-items.json
prefactor agent_spans create --payload @./span.json

Use this to keep large payloads in versioned files rather than inline in shell history.

Section titled “Related”