CI/CD Integration

The Foir CLI is designed to work in automated environments. This guide covers headless authentication, running code generation in CI, and example workflows for common platforms.

Headless Authentication

In CI/CD environments, use the FOIR_API_KEY environment variable instead of interactive OAuth login. When this variable is set, the CLI authenticates directly without requiring browser interaction.


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

You can create an API key for CI use through the CLI or the platform dashboard:


# Create an API key locally
foir api-keys create --data '{"name":"CI Pipeline"}'

Store the returned key as a secret in your CI platform (e.g., GitHub Actions secrets, GitLab CI variables).

Environment Variables

These environment variables configure the CLI in CI environments:

Variable	Description	Required
`FOIR_API_KEY`	API key for authentication	Yes
`FOIR_API_URL`	Override the API endpoint URL (default: `https://api.foir.io`)	No
`FOIR_STORAGE_URL`	Override the storage endpoint URL (default: `https://storage.foir.dev`)	No
`FOIR_PROJECT`	Named profile to use (if you have multiple profiles configured)	No

Running Code Generation in CI

Running foir pull in CI ensures your generated types stay in sync with your platform models. This is especially useful when models can be modified through the platform dashboard.


FOIR_API_KEY=$FOIR_API_KEY foir pull --no-prettier

The --no-prettier flag is recommended in CI to skip formatting and speed up the generation step. Your project’s build or lint step can handle formatting separately if needed.

GitHub Actions Examples

Generate Types on Build

Run foir pull as part of your build pipeline to ensure types are always up to date:


# .github/workflows/build.yml
name: Build
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - run: npm ci
 
      - name: Generate types from Foir
        env:
          FOIR_API_KEY: ${{ secrets.FOIR_API_KEY }}
        run: npx @eide/foir-cli pull --no-prettier
 
      - name: Build
        run: npm run build

Seed Content from Repository

Push content files to the platform whenever they change:


# .github/workflows/seed-content.yml
name: Seed Content
 
on:
  push:
    branches: [main]
    paths: ['content/**']
 
jobs:
  seed:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install Foir CLI
        run: npm install -g @eide/foir-cli
 
      - name: Seed records
        env:
          FOIR_API_KEY: ${{ secrets.FOIR_API_KEY }}
        run: |
          for f in content/*.json; do
            echo "Creating record from $f"
            foir records create page --file "$f" --json
          done

Push Config Changes

Automatically push config changes when your foir.config.ts file is modified:


# .github/workflows/push-config.yml
name: Push Config
 
on:
  push:
    branches: [main]
    paths: ['foir.config.ts']
 
jobs:
  push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - run: npm ci
 
      - name: Push config to platform
        env:
          FOIR_API_KEY: ${{ secrets.FOIR_API_KEY }}
        run: npx @eide/foir-cli push

Scheduled Model Sync

Use a cron-triggered workflow to keep your generated types fresh on a schedule:


# .github/workflows/sync-types.yml
name: Sync Generated Types
 
on:
  schedule:
    - cron: '0 6 * * 1-5'  # Weekdays at 6 AM UTC
  workflow_dispatch:
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - run: npm ci
 
      - name: Generate types
        env:
          FOIR_API_KEY: ${{ secrets.FOIR_API_KEY }}
        run: npx @eide/foir-cli pull
 
      - name: Check for changes
        id: changes
        run: |
          if [ -n "$(git status --porcelain src/generated/)" ]; then
            echo "has_changes=true" >> $GITHUB_OUTPUT
          fi
 
      - name: Commit and push
        if: steps.changes.outputs.has_changes == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add src/generated/
          git commit -m "chore: sync generated types from Foir"
          git push

Tips

Use --json for scripting. When parsing CLI output in scripts, always use the --json flag to get structured output instead of the human-readable table format.
Use --quiet for pipelines. When you only need IDs (e.g., to pipe into another command), --quiet outputs one ID per line with no other formatting.
Pin the CLI version. In CI, install a specific version (npm install -g @eide/foir-cli@1.x.x) to avoid unexpected breaking changes.
Use npx to avoid global installs. If the CLI is a dev dependency, npx @eide/foir-cli runs it without a global install step.