Command Reference

foir login [options]

# Default: opens a local browser
foir login
 
# Headless: approve a short code on any device (SSH / containers / CI)
foir login --device
 
# Out-of-band: paste a one-time code back into the terminal
foir login --no-browser

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

foir workspaces create --name <name> [options]

# Create a workspace and start pushing immediately
foir workspaces create --name "Acme Studio" --select
foir push
 
# Scripting-friendly output
foir workspaces create --name "Acme Studio" --json

foir projects create --name <name> [options]

# Create in the active workspace and switch to it
foir projects create --name "Marketing Site" --select
 
# Target a specific workspace
foir projects create --name "Marketing Site" --tenant ten_abc123

# List published records, page size 10
foir records list blog-post --filter "status=published" --first 10
 
# Get a record by natural key (model key is positional)
foir records get page hello-world
 
# Get the resolved published content
foir records get page hello-world --resolved
 
# Create a record from a JSON file
foir records create page --file page.json
 
# Atomic draft save (data + version + currentVersionId)
foir records save page clx123 --file page.json --message "Update hero copy"
 
# Publish a version by its version ID
foir records publish ver_abc123
 
# List all versions of a record
foir records versions clx1234567890

# List models in a category
foir models list --category content
 
# Search models by name
foir models list --search blog
 
# Create a model from a JSON file
foir models create --file blog-post-model.json
 
# Update a model by key
foir models update blog-post --file blog-post-model.json
 
# View schema version history (by model key)
foir models versions blog-post

# 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 --first 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 active customers
foir customers list --status active
 
# Get a customer by email
foir customers get user@example.com
 
# Create a customer
foir customers create --email new@example.com
 
# Create a customer with extra data
foir customers create --email new@example.com --data '{"name":"New User"}'

# List customer roles
foir customer-roles list
 
# Create a default role granting self-access to customer-writable records
foir customer-roles create --key default --name "Default" --permissions "self:*" --default
 
# Add operation execution to a role
foir customer-roles update clx_role_123 --permissions "self:*,operations:execute"
 
# Assign a role to a specific customer
foir customer-roles assign --customer clx_cust_456 --role clx_role_123
 
# List a customer's role assignments
foir customer-roles assignments --customer clx_cust_456
 
# Revoke an assignment
foir customer-roles revoke clx_assign_789 --confirm

# List context dimensions (segments + model sources)
foir context-dimensions list
 
# Create a segment from JSON
foir context-dimensions create --data '{
  "key": "gold",
  "name": "Gold",
  "sourceType": "segment",
  "evaluationRules": { "type": "group", "logicalOperator": "AND", "conditions": [] }
}'

# 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}'

# See which projects you can use and which is active
foir context projects
 
# Switch to a different project
foir context switch prj_abc123
 
# List available tenants
foir context tenants

# List all operations
foir operations list
 
# Execute an operation with input data (key is positional)
foir operations execute send-welcome-email --data '{"userId":"clx123"}'
 
# Execute asynchronously
foir operations execute long-running-report --data '{"month":"2026-05"}' --async
 
# View the 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 --first 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 (key and value are positional)
foir settings set site.name "My Site" --category general
 
# Reset a setting back to its default
foir settings reset site.name

# 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 (key, name, and type are required)
foir auth-providers create \
  --key google \
  --name "Google" \
  --type OAUTH2 \
  --enabled \
  --file google-auth.json

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

# List configured push credentials
foir push-credentials list
 
# Upload an APNs key for iOS (sandbox by default)
foir push-credentials upload-ios \
  --p8 ./AuthKey_ABC123.p8 \
  --bundle-id com.example.app \
  --team-id A1B2C3D4E5 \
  --key-id F6G7H8I9J0
 
# Upload the same key for production
foir push-creds upload-ios --p8 ./AuthKey_ABC123.p8 --bundle-id com.example.app \
  --team-id A1B2C3D4E5 --key-id F6G7H8I9J0 --production
 
# Upload an FCM service-account for Android
foir push-credentials upload-android --service-account ./firebase-service-account.json
 
# Delete a credential
foir push-credentials delete cred_abc123

# List unresolved notes on a record
foir notes list --entity-type record --entity-id clx123
 
# Create a note on a record
foir notes create --entity-type record --entity-id clx123 --body "Needs review before publishing"
 
# Resolve a note
foir notes resolve clx_note_456 --resolution "Reviewed and approved"
 
# 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
 
# Tunnel a local app dev server (on :5173) and re-push on config changes
foir apps dev --port 5173 --watch
 
# Use a BYO tunnel URL instead of cloudflared
foir apps dev --tunnel none --url https://my-tunnel.example.com --push

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

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

# 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
 
# Create a config
foir configs create --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
 
# Preview the create / update / delete plan without changing anything
foir push --dry-run
 
# In CI: allow deletions to proceed without an interactive prompt
foir push --allow-delete

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 archive you can restore later
foir export postgres
 
# …somewhere specific
foir export postgres --out ./backups/myproject.tar.gz
 
# Restore straight into a database you own (never leaves your machine)
foir export postgres --target "postgresql://user:pass@localhost:5432/myproject"
 
# With PostGIS geometry and the full-fidelity mirror
foir export postgres --postgis --include-raw --target "$DATABASE_URL"

# Write an embedding from a file
foir embeddings write --file embeddings.json
 
# Semantic search by vector similarity
foir embeddings search --data '{"queryVector":[0.12,0.04,-0.31],"modelKey":"article","first":10}'
 
# Find similar records, scoped to a model
foir embeddings similar clx123 --model-key article --first 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