---
title: CLI configuration
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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

## 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](/admin-ui/account/api-tokens) for that profile.

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

### 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

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

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

```bash
git check-ignore prefactor.json
git status --short
```

## JSON input from files

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

```bash
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.

## Related

- [Getting started with the CLI](/cli/getting-started) — install and first-run walkthrough
- [API tokens](/admin-ui/account/api-tokens) — create and manage the tokens your profiles use