Command-line interface
Install, authenticate, discover commands, and automate the tenant CLI safely.
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 --helpThe 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 logoutTo import an existing API key, keep it out of shell history and process listings:
openfactor auth import --token-stdin < /run/secrets/openfactor-api-keyFor 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-tokenDiscover and run commands
Help is generated from the same catalog used for execution and completions:
openfactor --help
openfactor projects --help
openfactor projects get --help
openfactor projects get --help --verboseCommand help leads with examples and arguments. --verbose adds raw input and
output schemas when needed. Requests use schema-derived flags such as
--team-id, --limit, and --name:
openfactor projects list --team-id TEAM_ID
openfactor projects get --team-id TEAM_ID --project-id PROJECT_IDSupply 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 projects get --input-file ./request.json
cat request.json | openfactor projects get --input-file - --project-id OTHEROutput 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 --team-id TEAM_ID --json
openfactor projects list --team-id TEAM_ID --plain
openfactor projects list --team-id TEAM_ID --format yaml
openfactor projects list --team-id TEAM_ID --format toon
openfactor projects list --team-id TEAM_ID --filter-output projectsDiagnostics 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. For
unattended destructive operations, pass --yes; otherwise the CLI requires
confirmation. Use --dry-run to preview a destructive command without executing
it.
openfactor projects delete \
--team-id TEAM_ID \
--project-id PROJECT_ID \
--dry-run --json
openfactor projects delete \
--team-id TEAM_ID \
--project-id PROJECT_ID \
--no-input --yes --jsonNetwork 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.
Exit codes
Scripts can branch on these stable exit codes:
| Code | Meaning |
|---|---|
0 | Success |
1 | CLI-level failure outside the mapped error kinds |
2 | Usage error in the command or its flags |
66 | The requested resource was not found |
70 | Internal error or output failure |
73 | State conflict, such as a concurrent change |
75 | Rate limited; the request is retryable |
77 | Authentication or permission failure |
127 | Unknown command name |
130 | Interrupted by SIGINT (Ctrl-C) |
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, --yesGenerate automation-oriented catalogs or install shell completions with:
openfactor --llms
openfactor --schemaFor Zsh:
mkdir -p ~/.zfunc
openfactor completion zsh > ~/.zfunc/_openfactor
print -r -- 'fpath=(~/.zfunc $fpath)' >> ~/.zshrcFor Bash:
mkdir -p ~/.local/share/bash-completion/completions
openfactor completion bash > ~/.local/share/bash-completion/completions/openfactorFor Fish:
mkdir -p ~/.config/fish/completions
openfactor completion fish > ~/.config/fish/completions/openfactor.fishopenfactor 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 schemasNon-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 codes - branch on the exit-code table
When a command fails in a machine format, the error envelope includes a
docsCommand field with the exact guide command to run for remediation.
Next steps
- API keys - create a key for API access
- Start a workflow - make a first Developer API request
- Billing - understand wallet balances and usage