The Open Factor CLI is a self-contained macOS or Linux binary named openfactor.

Install

The installer endpoint shown below is the shared release service for all tenants; it selects the tenant-specific binary named below.

curl -fsSL https://assets.openfactor.ai/cli/releases/install.sh | sh -s -- openfactor
openfactor --version
openfactor --help

The installer detects the operating system and CPU, verifies the release's SHA-256 checksum, and installs into ~/.local/bin. Set CLI_INSTALL_DIR to use another directory, CLI_VERSION to pin a release, or CLI_TIMEOUT_SECONDS to change the installer's 60-second network timeout.

Upgrade or remove the binary with:

openfactor upgrade
openfactor auth logout
rm ~/.local/share/bash-completion/completions/openfactor
rm ~/.config/fish/completions/openfactor.fish
rm ~/.zfunc/_openfactor
rm "${CLI_INSTALL_DIR:-$HOME/.local/bin}/openfactor"

Authenticate

The recommended flow opens a browser and saves the API key in macOS Keychain or Linux Secret Service:

openfactor auth login
openfactor auth status
openfactor auth logout

To import an existing API key, keep it out of shell history and process listings:

openfactor auth import --token-stdin < /run/secrets/openfactor-api-key

For a single command in a container or CI job, use a mode-0600 credential file. The CLI reads it but never creates a plaintext credential file:

install -m 600 /run/secrets/openfactor-api-key /tmp/openfactor-token
openfactor auth status --credential-file /tmp/openfactor-token --json
rm /tmp/openfactor-token

Discover and run commands

Help is generated from the same catalog used for execution and completions:

openfactor --help
openfactor projects --help
openfactor project get --help
openfactor project get --help --verbose

Command help leads with examples and arguments. --verbose adds raw input and output schemas when needed. Requests use schema-derived flags such as --path.teamId, --query.limit, and --body.name:

openfactor projects list --path.teamId TEAM_ID
openfactor project get --path.teamId TEAM_ID --path.projectId PROJECT_ID

Supply a whole request with --input-file. The file is a JSON object with optional path, query, and body keys, and - reads it from standard input. Schema-derived flags override the file at their own key path, so a shared template can be reused with per-call overrides:

openfactor project get --input-file ./request.json
cat request.json | openfactor project get --input-file - --path.projectId OTHER

Output and automation

Interactive output is optimized for people. When stdout is redirected or piped, the default is stable JSON. Select a format explicitly when a script depends on it:

openfactor projects list --path.teamId TEAM_ID --json
openfactor projects list --path.teamId TEAM_ID --plain
openfactor projects list --path.teamId TEAM_ID --format yaml
openfactor projects list --path.teamId TEAM_ID --format toon
openfactor projects list --path.teamId TEAM_ID --filter-output data.projects

Diagnostics and progress go to stderr; command data goes to stdout. The Running <command>... progress line appears only when stderr is a terminal. --verbose prints one stderr line per HTTP attempt with the method, URL, status, duration, and retry counter, and stays enabled alongside --quiet. Successful commands exit 0, usage errors exit 2, missing commands exit 127, and other failures are non-zero. For unattended destructive operations, pass --yes; otherwise the CLI requires confirmation. Use --dry-run to preview a destructive command without executing it.

openfactor project delete \
  --path.teamId TEAM_ID \
  --path.projectId PROJECT_ID \
  --dry-run --json
 
openfactor project delete \
  --path.teamId TEAM_ID \
  --path.projectId PROJECT_ID \
  --no-input --yes --json

Network requests time out after 30 seconds by default. Override the timeout in milliseconds with --timeout; press Ctrl-C once for graceful cancellation and a second time to force exit.

Common global options are:

--json, --plain, --format human|plain|toon|json|yaml|markdown|jsonl
--filter-output PATH, --full-output
--token-limit N, --token-offset N
--input-file PATH|-, --credential-file PATH, --timeout MILLISECONDS
-q, --quiet, -d, --debug, --verbose
--no-input, --dry-run, --yes

Generate automation-oriented catalogs or install shell completions with:

openfactor --llms
openfactor --schema

For Zsh:

mkdir -p ~/.zfunc
openfactor completion zsh > ~/.zfunc/_openfactor
print -r -- 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc

For Bash:

mkdir -p ~/.local/share/bash-completion/completions
openfactor completion bash > ~/.local/share/bash-completion/completions/openfactor

For Fish:

mkdir -p ~/.config/fish/completions
openfactor completion fish > ~/.config/fish/completions/openfactor.fish

openfactor mcp and openfactor serve expose opt-in local adapters. They are not required for ordinary CLI use.

Getting help

Start with openfactor <command> --help. Unknown commands suggest a nearby valid command and a help path. For account support, use the support link shown in root help.

For AI agents

The binary carries its own command catalog and task guides. Agents should use discovery commands rather than a static file that could drift from the installed version.

openfactor docs list              # all task guides, one row each
openfactor docs list --json       # same, as structured JSON
openfactor docs show automation   # full scripting and non-interactive guide
openfactor docs show authentication  # auth setup and credential management
openfactor --llms                 # machine-readable catalog with schemas
openfactor <command> --help --verbose  # command flags + raw schemas

Non-interactive essentials:

• --yes - skip confirmation prompts on destructive commands
• --no-input - fail rather than block on interactive input
• --input-file PATH|- - supply request JSON from a file or stdin
• --json - stable JSON on stdout
• Exit 77 = auth error, 75 = rate limit / retryable, 2 = usage error

When a command fails in a machine format, the error envelope includes a docsCommand field with the exact guide command to run for remediation.