Command Reference

foir login

foir logout

foir whoami

foir select-project [options]

# Interactive picker
foir select-project
 
# Switch without the prompt
foir select-project --project-id prj_abc123
 
# Save the selection as a profile so you can switch back later
foir select-project --project-id prj_abc123 --save-as staging

# List profiles
foir profiles list
 
# Inspect the active profile
foir profiles show
 
# Set the default profile so naked CLI calls use staging
foir profiles default staging
 
# Remove a profile
foir profiles delete old-tenant --confirm

# List published records with sorting
foir records list blog-post --filter "status=published" --sort "createdAt:desc" --limit 10
 
# Get a record by natural key (requires --model-key)
foir records get hello-world --model-key page
 
# Create a record from a JSON file and publish it
foir records create page --file page.json --publish
 
# Publish using a natural key instead of version ID
foir records publish my-page --model-key page
 
# List all versions of a record
foir records versions clx1234567890

# List all models
foir models list
 
# Create a model from a JSON file
foir models create --file blog-post-model.json
 
# Create models from all files in a directory, updating if they already exist
foir models create --dir ./models --upsert
 
# View schema version history
foir models versions clx1234567890

# List all locales
foir locales list
 
# Get a locale by code
foir locales get en-US
 
# Get the default locale
foir locales default
 
# Create a new locale
foir locales create --data '{"locale":"fr-FR","displayName":"French","nativeName":"Francais"}'

# Upload a file to a specific folder
foir media upload ./images/hero.jpg --folder banners
 
# List files filtered by folder
foir media list --folder banners
 
# Search for files
foir media list --search "hero"
 
# Update file metadata
foir media update-metadata clx123 --alt-text "Hero banner image" --caption "Welcome banner"
 
# Check storage usage
foir media usage
 
# Permanently delete a file (cannot be restored)
foir media delete clx123 --confirm --permanent

# List images in the /banners folder
foir files list --folder banners --mime-type image/jpeg
 
# Search by filename
foir files list --search hero
 
# Move a file to a different folder
foir files update clx123 --folder archive
 
# Tag a file
foir files update clx123 --tags "homepage,launch,q2"
 
# Add alt text + caption for accessibility / SEO
foir files update-metadata clx123 \
  --alt-text "A woman walking through a field of barley at sunrise" \
  --caption "Spring '26 campaign"
 
# Storage usage summary
foir files usage --json

foir search <query> [options]

# Search across all content
foir search "getting started"
 
# Search within specific models
foir search "pricing" --models page,blog-post --limit 5
 
# Output as JSON for scripting
foir search "hello" --json

# Create a rollout scheduled for next Monday
foir rollouts create --data '{
  "name": "Weekly Release",
  "scheduledAt": "2026-05-19T09:00:00Z",
  "items": [
    { "kind": "record", "versionId": "ver_abc123" },
    { "kind": "record", "versionId": "ver_def456" }
  ]
}'
 
# Inspect the rollout, including its items
foir rollouts get rollout_abc123 --json
 
# Add more items to a draft rollout
foir rollouts add-items rollout_abc123 --file ./additional-items.json
 
# Trigger immediately, skipping the scheduled time
foir rollouts trigger rollout_abc123
 
# Pause while it runs, then resume
foir rollouts pause rollout_abc123
foir rollouts resume rollout_abc123
 
# Retry items that failed during the run
foir rollouts retry rollout_abc123
 
# Preview a rollback before committing
foir rollouts rollback rollout_abc123 --preview
 
# Execute the rollback
foir rollouts rollback rollout_abc123 --confirm
 
# Delete a rollout that never ran
foir rollouts delete rollout_abc123 --confirm

# List all customers
foir customers list
 
# Get a customer by email
foir customers get user@example.com
 
# Create a customer
foir customers create --data '{"email":"new@example.com","name":"New User"}'

# View the current profile schema
foir customer-profiles schema --json
 
# Update the profile schema
foir customer-profiles update-schema --file profile-schema.json
 
# Set profile data for a customer
foir customer-profiles set clx123 --data '{"preferences":{"theme":"dark"}}'

# List active segments
foir segments list
 
# Preview rules before saving
foir segments preview --file segment-rules.json
 
# Test a segment against a specific customer
foir segments test clx_seg_123 clx_cust_456

# List all variant catalog entries
foir variant-catalog list
 
# Get a variant by key
foir variant-catalog get premium-users
 
# Create a new variant catalog entry
foir variant-catalog create --data '{"key":"mobile","name":"Mobile Users","isActive":true}'

# List all context dimensions
foir context list
 
# Get a context dimension by key
foir context get device-type
 
# Create a new context dimension
foir context create --data '{"key":"region","name":"Region"}'

# List all operations
foir operations list
 
# Execute an operation with input data
foir operations execute --data '{"key":"send-welcome-email","input":{"userId":"clx123"}}'
 
# View dead letter queue
foir operations dead-letters
 
# Retry a failed operation
foir operations retry-dead-letter clx_dl_456

# List active hooks for a specific event
foir hooks list --event record.published --active
 
# Create a hook from a JSON file
foir hooks create --file ./hooks/on-publish.json
 
# Inline create
foir hooks create --data '{"key":"on-publish","name":"On Publish","event":"record.published","url":"https://example.com/webhook"}'
 
# Deactivate without removing
foir hooks update hook_abc123 --no-active
 
# Recent failed deliveries for a hook
foir hooks deliveries hook_abc123 --status failed --limit 20
 
# Send a synthetic delivery to verify the receiver
foir hooks test hook_abc123 --data '{"message":"test"}'
 
# Retry one failed delivery
foir hooks retry-delivery del_456

# List all schedules
foir schedules list
 
# Create a scheduled task
foir schedules create --file daily-sync.json
 
# Trigger a schedule immediately (outside its cron)
foir schedules trigger daily-sync
 
# Pause a schedule
foir schedules pause daily-sync

# List all settings
foir settings list
 
# Get a specific setting
foir settings get site.name
 
# Set a setting value
foir settings set --data '{"key":"site.name","value":"My Site"}'

# Print the draft document as JSON
foir design-tokens get
 
# Print the resolved view (groups expanded into flat arrays)
foir design-tokens get --resolved
 
# Diff what the storefront is serving against the draft
foir design-tokens get --channel published > published.json
foir design-tokens get --channel draft     > draft.json
diff published.json draft.json
 
# Apply a hand-authored or generated tokens document
foir design-tokens apply ./tokens.json
 
# Apply and publish in one step
foir design-tokens apply ./tokens.json --publish
 
# Promote the current draft to published
foir design-tokens publish
 
# Check whether draft and published are in sync
foir design-tokens status

# Store a new secret from a file (binary-safe)
foir secrets put --file ./stripe.key --label "Stripe API key"
 
# Store a string value
foir secrets put --value "sk_test_..." --label "Stripe (test)"
 
# List project-owned secrets
foir secrets list
 
# Reconcile a declarative secrets file
foir secrets push --config foir.secrets.ts --plaintext local.foir.secrets.ts
 
# Rotate (returns a new ref — update your app code)
foir secrets rotate vault:abc123 --file ./new-stripe.key
 
# Soft-delete and undo
foir secrets delete vault:abc123 --confirm
foir secrets restore vault:abc123

# List all API keys
foir api-keys list
 
# Create a new API key
foir api-keys create --data '{"name":"CI Pipeline"}'
 
# Rotate an existing key (requires confirmation)
foir api-keys rotate clx123 --confirm
 
# Revoke a key
foir api-keys revoke clx123 --confirm

# List configured auth providers
foir auth-providers list
 
# Create a Google OAuth provider
foir auth-providers create --file google-auth.json

# Show the active customer-auth configuration
foir auth config --json
 
# Verify a JWT carried in a request header during local debugging
foir auth verify-token "eyJhbGciOi..."

# List unread notifications
foir notifications list
 
# Mark all as read
foir notifications read-all

# Create a note on a record
foir notes create --data '{"entityType":"record","entityId":"clx123","content":"Needs review before publishing"}'
 
# Resolve a note
foir notes resolve --data '{"id":"clx_note_456"}'
 
# Delete a note
foir notes delete clx_note_456 --confirm

# List installed apps
foir apps list
 
# Install with inline mappings (ad-hoc)
foir apps install https://shopify.apps.foir.io/manifest.json \
  --source-map '{"product":{"toModel":"product","naturalKey":"handle","fields":{"title":"title","handle":"handle"}}}'
 
# Install via foir.config.ts (golden path) — declare apps.<name> and run:
foir push
 
# Check for updates with a diff
foir apps update redirector --dry-run
 
# Apply updates (only safe-auto changes apply automatically; rejected changes block)
foir apps update redirector
 
# Trigger a specific operation on an installed app
foir apps trigger redirector deploy-worker --data '{"force":true}'
 
# Force-uninstall (skip middleware __uninstall, remove platform state regardless)
foir apps uninstall redirector --force
 
# Validate a manifest before installing
foir apps validate https://my-app.example.com/manifest.json

npx @eide/foir-cli create-config <name> [options]

# Custom editor placement (UI + middleware)
npx @eide/foir-cli create-config my-editor --type custom-editor
 
# Pure backend operation (no UI)
npx @eide/foir-cli create-config my-summarizer --type workflow
 
# Static iframe (no middleware)
npx @eide/foir-cli create-config color-picker --type widget

# Scaffold a fresh foir.config.ts in this folder
foir init
 
# Create a starter model file at ./models/blog-post.ts
foir init model blog-post --ts
 
# Generate seed records into ./seed/ for models you pick interactively
foir init records --ts

# List all configs
foir configs list
 
# Get a config by key
foir configs get my-blog-config
 
# Apply a config
foir configs apply --file config.json
 
# Trigger a sync
foir configs sync clx123

foir pull [options]

# Pull the current project's config into ./foir.config.ts
foir pull
 
# Pull a named config and write to a different file
foir pull --key my-blog-config --out ./configs/blog.config.ts
 
# Overwrite without prompt (useful in CI / pre-commit hooks)
foir pull --force

foir push [options]

# Push the config file in the current directory
foir push
 
# Push a specific config file
foir push --config ./configs/blog.config.ts
 
# Apply and publish in one step — including design tokens
foir push --publish
 
# Overwrite admin-UI edits when the three-way merge reports conflicts
foir push --force

foir remove <key> [options]

# Remove a config (with confirmation prompt)
foir remove my-blog-config
 
# Remove without confirmation
foir remove my-blog-config --force

# Write an embedding from a file
foir embeddings write --file embeddings.json
 
# Semantic search (JSON payload describes the query)
foir embeddings search --data '{"query":"machine learning","modelKey":"article","limit":10}'
 
# Find similar records, scoped to a model
foir embeddings similar clx123 --model-key article --limit 5
 
# Embedding statistics for a single model
foir embeddings stats article --json
 
# Project-wide stats (no model key)
foir embeddings stats --json
 
# Delete the embedding attached to a record
foir embeddings delete clx123 --confirm