Foir CLI

The Foir CLI (foir) is a command-line interface for the Foir platform. It provides resource-oriented CRUD commands across the entire platform, composable output modes for scripting, and supports both OAuth and API key authentication.

Installation

# Install globally
npm install -g @eide/foir-cli
 
# Or use with npx (no installation required)
npx @eide/foir-cli
 
# Or add as a dev dependency
npm install -D @eide/foir-cli

Quick Start

1. Authenticate

foir login

This opens your browser for OAuth authentication. After logging in, credentials are stored locally in ~/.foir/.

2. Select a Project

foir select-project

Choose your tenant and project from the interactive menu. This provisions a scoped API key and stores the project context in .foir/project.json relative to your repository root.

3. Start Using the CLI

# List records for a model
foir records list page
 
# Create a record
foir records create page --data '{"title":"Hello World","slug":"hello-world"}'
 
# Get a record by natural key
foir records get page hello-world --model-key page
 
# Search across all content
foir search "hello" --models page,blog-post

Authentication

Foir CLI supports two authentication modes.

Interactive (OAuth)

For local development, authenticate through your browser:

foir login                 # Authenticate via browser
foir whoami                # Check current auth status
foir select-project        # Choose a project
foir logout                # Clear stored credentials

Headless (API Key)

For CI/CD pipelines, scripts, and automated workflows, set the FOIR_API_KEY environment variable:

export FOIR_API_KEY=sk_live_abc123...
foir records list page --json

When FOIR_API_KEY is set, the CLI skips the OAuth flow entirely and authenticates directly with the API key.

Project Selection and Profiles

After logging in, you must select a project. The CLI supports named profiles so you can work with multiple projects without re-authenticating.

Saving a Named Profile

foir select-project --save-as staging
foir select-project --save-as production

Using Profiles

# Use a specific profile for a command
foir records list page --project staging
 
# Or set a default profile
foir profiles default production
 
# List all saved profiles
foir profiles list
 
# Show details of the active profile
foir profiles show

Project Resolution Order

When running a command, the CLI resolves the project context in this order:

1. --project <name> flag on the command
2. FOIR_PROJECT environment variable
3. Default profile (set via foir profiles default)
4. .foir/project.json (created by foir select-project without --save-as)

Global Options

Every command accepts these global options:

Output Modes

Every command supports four output modes for different use cases:

Examples

# Human-readable table (default)
foir records list page
 
# JSON for scripting
foir records list page --json
 
# Pipe IDs to another command
foir records list page --quiet | head -5
 
# JSONL for streaming processing
foir records list page --jsonl

Environment Variables

Input Methods

Commands that create or update resources accept data through three methods:

# Inline JSON with --data
foir records create page --data '{"title":"Hello","slug":"hello"}'
 
# From a JSON file with --file
foir records create page --file record.json
 
# Pipe from stdin
cat record.json | foir records create page

Filtering and Sorting

List commands support --filter and --sort options for querying:

# Filter with operators
foir records list page --filter "status=published"
foir records list page --filter "createdAt>2025-01-01"
foir records list page --filter "title~%hello%"
 
# Sort results
foir records list page --sort "createdAt:desc"
 
# Combine with pagination
foir records list page --filter "status=published" --sort "updatedAt:desc" --limit 10 --offset 20

Filter Operators

Next Steps

• Command Reference — Full reference for all command groups
• Code Generation — Generate TypeScript types and GraphQL documents from your models
• CI/CD Integration — Use Foir CLI in automated pipelines