Command-line interface

The FactorAI CLI is a self-contained macOS or Linux binary named factorai.

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.factorai.ai/cli/releases/install.sh | sh -s -- factorai
factorai --version
factorai --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:

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

Authenticate#

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

factorai auth login
factorai auth status
factorai auth logout

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

factorai auth import --token-stdin < /run/secrets/factorai-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/factorai-api-key /tmp/factorai-token
factorai auth status --credential-file /tmp/factorai-token --json
rm /tmp/factorai-token

Discover and run commands#

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

factorai --help
factorai projects --help
factorai project get --help
factorai 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:

factorai projects list --path.teamId TEAM_ID
factorai 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:

factorai project get --input-file ./request.json
cat request.json | factorai 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:

factorai projects list --path.teamId TEAM_ID --json
factorai projects list --path.teamId TEAM_ID --plain
factorai projects list --path.teamId TEAM_ID --format yaml
factorai projects list --path.teamId TEAM_ID --format toon
factorai projects list --path.teamId TEAM_ID --filter-output 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. For unattended destructive operations, pass --yes; otherwise the CLI requires confirmation. Use --dry-run to preview a destructive command without executing it.

factorai project delete \
  --path.teamId TEAM_ID \
  --path.projectId PROJECT_ID \
  --dry-run --json

factorai 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.

Exit codes#

Scripts can branch on these stable exit codes:

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:

factorai --llms
factorai --schema

For Zsh:

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

For Bash:

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

For Fish:

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

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

Getting help#

Start with factorai <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.

factorai docs list              # all task guides, one row each
factorai docs list --json       # same, as structured JSON
factorai docs show automation   # full scripting and non-interactive guide
factorai docs show authentication  # auth setup and credential management
factorai --llms                 # machine-readable catalog with schemas
factorai <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 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