Settings

Project-level configuration settings let you store and manage key-value pairs that control how your project behaves. Use settings for feature flags, configuration values, and shared constants.

Overview

Settings are project-scoped key-value pairs that you can read and write from the admin dashboard, the CLI, or the API. They provide a centralized place to manage configuration without redeploying code.

Each setting has:

Settings are available to your application at runtime through the API, making them useful for configuration that needs to change without a code deploy.

In the Admin

Viewing Settings

1. Navigate to Settings > Project Settings > Configuration
2. Browse all settings for your project
3. Use the search bar to find specific settings by key

Creating a Setting

1. Click Add Setting
2. Enter a key (use dot notation for organization, e.g., site.title)
3. Enter the value
4. Optionally add a description
5. Click Save

Editing a Setting

1. Find the setting in the list
2. Click Edit
3. Update the value
4. Click Save

Deleting a Setting

1. Find the setting in the list
2. Click Delete
3. Confirm the deletion

Via the CLI

# List all settings
foir settings list
 
# Get a specific setting by key
foir settings get site.title
 
# Set a value (creates or updates)
foir settings set --data '{
  "key": "site.title",
  "value": "My Project",
  "description": "The public-facing site title"
}'
 
# Set a JSON value
foir settings set --data '{
  "key": "features.flags",
  "value": { "newCheckout": true, "darkMode": false }
}'
 
# Delete a setting
foir settings delete site.title

Via the API

Query a Setting

query GetSetting {
  setting(key: "site.title") {
    key
    value
    description
    updatedAt
  }
}

List All Settings

query ListSettings {
  settings {
    items {
      key
      value
      description
      updatedAt
    }
  }
}

Update a Setting

mutation SetSetting {
  setSetting(input: {
    key: "site.title"
    value: "My Project"
    description: "The public-facing site title"
  }) {
    key
    value
    updatedAt
  }
}

Delete a Setting

mutation DeleteSetting {
  deleteSetting(key: "site.title") {
    success
  }
}

Common Settings Examples

Best Practices

• Use dot notation for keys to organize settings into logical groups (e.g., site.title, site.description, features.darkMode).
• Add descriptions to every setting so team members understand what each one controls.
• Use settings for runtime configuration that may need to change without a code deploy — feature flags, display values, integration parameters.
• Do not store secrets in settings — use environment variables or API keys for sensitive values. Settings are readable by anyone with project access.
• Keep values simple — prefer primitive values (strings, numbers, booleans) over deeply nested JSON when possible.