CI/CD Integration

The Foir CLI is designed to work in automated environments. This guide covers headless authentication, applying and exporting config (foir push / foir pull) 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_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).

If you need to authenticate as a user from a headless machine (SSH session, container, or CI shell) rather than with an API key, run foir login --device. This uses the device flow: the CLI prints a short code and a URL you approve from a browser on any device — no local browser or callback server is required. It is auto-selected when no local browser is detected.

Environment Variables

These environment variables configure the CLI in CI environments:

Applying and Exporting Config in CI

The CLI manages your project’s config-as-code in two directions:

• foir push applies a local foir.config.ts to the platform — registering or updating models, operations, hooks, schedules, and other declared resources. This is the command you run in CI to keep the platform in sync with source control.
• foir pull exports the platform’s current state of a config back into a local foir.config.ts. Use it to capture changes an admin made in the dashboard so they land in source control. It writes config only — there is no code/type generation step.

Both authenticate via FOIR_API_KEY in CI. See the push and pull references for the full flag list.

# Apply config-as-code to the platform
FOIR_API_KEY=$FOIR_API_KEY foir push
 
# Apply and publish updated resources in one step
FOIR_API_KEY=$FOIR_API_KEY foir push --publish

GitHub Actions Examples

Apply Config on Merge

Run foir push as part of your pipeline so merges to main reconcile the platform with your foir.config.ts:

# .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'
          cache: 'npm'
 
      - run: npm ci
 
      - name: Push config to platform
        env:
          FOIR_API_KEY: ${{ secrets.FOIR_API_KEY }}
        run: npx @foir/cli push --publish

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 @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

Sync Dashboard Edits Back to Source

Use a cron-triggered workflow to export platform changes (made by admins in the dashboard) back into foir.config.ts and open a PR / commit them:

# .github/workflows/sync-config.yml
name: Sync Config
 
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: Export config from Foir
        env:
          FOIR_API_KEY: ${{ secrets.FOIR_API_KEY }}
        run: npx @foir/cli pull --force
 
      - name: Check for changes
        id: changes
        run: |
          if [ -n "$(git status --porcelain foir.config.ts)" ]; 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 foir.config.ts
          git commit -m "chore: sync foir.config.ts from platform"
          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 @foir/cli@0.60.0) to avoid unexpected breaking changes.
• Use npx to avoid global installs. If the CLI is a dev dependency, npx @foir/cli runs it without a global install step.