@prefactor/cli

Command-line interface and typed API clients for managing Prefactor resources.

Installation

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/prefactordev/typescript-sdk/main/scripts/install.sh | bash

Install the canary channel:

curl -fsSL https://raw.githubusercontent.com/prefactordev/typescript-sdk/main/scripts/install.sh | bash -s -- latest

Install a pinned version:

curl -fsSL https://raw.githubusercontent.com/prefactordev/typescript-sdk/v0.0.5/scripts/install.sh | bash -s -- v0.0.5

Windows (PowerShell)

irm https://raw.githubusercontent.com/prefactordev/typescript-sdk/main/scripts/install.ps1 | iex

Install a pinned version:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/prefactordev/typescript-sdk/v0.0.5/scripts/install.ps1))) v0.0.5

Manual downloads

Standalone archives are published on GitHub Releases. Download the archive for your platform, extract it, and run:

./prefactor install

The managed install location is:

• macOS/Linux: ~/.prefactor/bin/prefactor
• Windows: %USERPROFILE%\.prefactor\bin\prefactor.exe

The installer does not edit your shell profile. It prints the exact PATH change needed if the managed bin directory is not already available.

Lifecycle commands

prefactor update
prefactor doctor
prefactor uninstall

npm package usage

The npm package remains available for programmatic usage:

npm install @prefactor/cli

Quick Start

1. Authenticate with your Prefactor account:

prefactor login

This opens your browser to the Prefactor login page. After authenticating, copy your API token and paste it into the prompt. Your credentials are saved automatically to the default profile.

2. Verify access:

prefactor accounts list
prefactor ping

3. Print setup values for an agent:

# Existing agent
prefactor setup <agent_id>

# Create a new agent, then print setup values
prefactor setup --create --name "<agent-name>" --description "<description>"

# Machine-readable output
prefactor setup <agent_id> --json

This verifies the selected profile can access the agent (or creates one with --create), resolves an environment for that agent (from an existing deployment when available), creates a deployment-scoped runtime API token (which creates a deployment if needed), pings that token to confirm it is valid for the agent, and prints shell-style setup values:

PREFACTOR_API_URL=...
PREFACTOR_API_TOKEN=...
PREFACTOR_AGENT_ID=...
PREFACTOR_AGENT_IDENTIFIER=1.0.0

If ping validation fails, setup exits with an error and does not treat the token as usable. PREFACTOR_API_TOKEN is an agent-deployment token. Use it for tracing from that agent deployment.

4. Query additional resources:

prefactor environments list --account_id <account_id>
prefactor agents list
prefactor api_tokens create --token_scope agent_deployment --agent_id <agent_id> --environment_id <environment_id>

Authentication and Profiles

The CLI reads credentials from profiles stored in prefactor.json:

• Uses <repo-root>/prefactor.json when one exists at the current git/worktree root.
• Otherwise uses <executable-root>/prefactor.json.
• If neither exists, creating a profile writes <executable-root>/prefactor.json.

Select a profile with either:

• Global flag: --profile <name>
• Environment variable: PREFACTOR_PROFILE=<name>

Environment fallback is supported when no default profile is configured:

• PREFACTOR_API_TOKEN
• PREFACTOR_API_URL (defaults to https://app.prefactorai.com)

Command Groups

• login: authenticate and save credentials to the default profile
• profiles: add, list, remove
• accounts: list, retrieve, update
• environments: list, retrieve, create, update, delete
• agents: list, retrieve, create, update, delete, retire, reinstate
• agent_deployments: list, retrieve, create, update, delete
• agent_versions: list, retrieve, create
• agent_schema_versions: list, retrieve, create
• agent_instances: list, retrieve, agent_context, register, start, finish
• agent_spans: list, create, finish, create_test_spans
• api_tokens: list, retrieve, create, suspend, activate, revoke, delete
• setup: create an agent (optional), mint a validated deployment token, and print setup values for instrumentation
• admin_users: list, retrieve
• admin_user_invites: list, retrieve, create, revoke
• pfid: generate
• bulk: execute
• ping: verify the selected or supplied API token

Run prefactor <command> --help for command-specific options.

JSON File Input

Some options accept JSON directly or from a file using @path syntax:

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

Programmatic Usage

@prefactor/cli also exports typed clients that can be used directly in scripts.

import {
  ApiClient,
  AccountClient,
  AgentClient,
  AgentDeploymentClient,
} from '@prefactor/cli';

const api = new ApiClient('https://app.prefactorai.com', process.env.PREFACTOR_API_TOKEN!);
const accounts = new AccountClient(api);
const agents = new AgentClient(api);
const deployments = new AgentDeploymentClient(api);

const accountList = await accounts.list();
const agentList = await agents.list();
const agentId = agentList.details[0]?.id;

if (accountList.details[0]?.id && agentId) {
  const deploymentList = await deployments.list(agentId);
  console.log(deploymentList.details);
}

API Reference

CLI Entry Points

• createCli(version: string): Command: Creates a configured Commander program instance.
• runCli(argv: string[]): Promise<void>: Parses and executes CLI commands.

Core API Client

• ApiClient: Shared HTTP client used by all resource clients.
  • request(path, options?): Sends a request to /api/v1 with query/body helpers.

Resource Clients

• AccountClient
• EnvironmentClient
• AgentClient
• AgentDeploymentClient
• AgentVersionClient
• AgentSchemaVersionClient
• AgentInstanceClient
• AgentSpanClient
• ApiTokenClient
• AdminUserClient
• AdminUserInviteClient
• PfidClient
• BulkClient

Each client exposes typed request/response interfaces for its resource operations.

Requirements

• Direct binary installs do not require Node.js or npm.
• Programmatic package usage requires Node.js >= 22.0.0.

License

MIT