keel.yaml reference
Every option of config/packages/keel.yaml, under keel:. Everything is optional: a missing key means the default shown here. Copy only what you change.
bin/console config:dump-reference keelprints the same options, each with a one-line explanation.- The bundle's
config/keel.example.yamlhas every key with its default (copied at the end of this page). - A wrong value stops
bin/console cache:clearwith a message that names the key and the value.
Placeholders in the keys: <css-var>, <pattern>, <Class> and <list-key> stand for a name you choose, one entry per colour, folder, class or list.
Look
| Key | Default | What it does |
|---|---|---|
title | Dashboard | Tab and header title |
subtitle | Content dashboard | Smaller text under the title |
logo | ~ (the Keel mark) | Image URL shown in the header |
website_url | / | Target of the header's View website button |
theme.<css-var> | none | Interface colour or value per theme variable, e.g. accent: '#0066A5'. All names: Name, logo and colours |
Content
| Key | Default | What it does |
|---|---|---|
classes.include | [] (all) | Class names that get an automatic list; empty = all |
classes.exclude | [] | Class names to hide |
collections.<list-key>.class | ~ | Class name; optional when changing an automatic list (key = class name in kebab case, SpecialOffer → special-offer) |
collections.<list-key>.enabled | true | false hides the list |
collections.<list-key>.title | the class title | List name in the menu |
collections.<list-key>.singular | the title | Name of one item, for "+ New …" |
collections.<list-key>.icon | the class icon | Menu icon |
collections.<list-key>.group | the class group | Menu group |
collections.<list-key>.condition | ~ | Database condition on the class's fields, e.g. type = "cruise" |
collections.<list-key>.folder | ~ | Parent folder of new objects |
collections.<list-key>.label | automatic | Field used as the row and item label |
collections.<list-key>.columns | [] (automatic) | Field names shown as table columns, in order (at most lists.max_columns, when set); Assigned to, Changed and Publication follow as always. Without them a list shows lists.default_columns columns |
collections.<list-key>.order_by | ~ (last change) | Field the list is sorted by |
collections.<list-key>.order | ~ (DESC) | ASC or DESC |
collections.<list-key>.defaults | {} | Field values for new objects |
collections.<list-key>.status_field | ~ (automatic) | Select field shown as status chips and Open / Closed tabs; Customize → Statuses wins over it |
scope.label | Market | Name of the header switcher |
scope.options | {} | The choices: key: {label, locale}; any other value, e.g. site: 2, is {scope.site} in urls |
scope.paths | [] | Object paths per option, each with {scope}, e.g. /Products/{scope}/ |
urls.<Class>.path | required | Website path with placeholders {id}, {key}, {locale}, {scope}, {scope.<name>}, {<field>} |
urls.<Class>.site | ~ | Pimcore site id or a placeholder such as {scope.site} |
urls.<Class>.domain | ~ | Public domain instead of a site |
urls.<Class>.published_only | true | Preview only published objects |
Pages: Content, Header switcher, Website pages.
Images and uploads
| Key | Default | What it does |
|---|---|---|
upload_folder | /dashboard-uploads | Asset folder for images uploaded in the editor |
image_folder | / | Asset folder the image picker searches |
folder_labels.<pattern>.class | required | Class of the objects the folders belong to; pattern e.g. /product-photos/{value} |
folder_labels.<pattern>.field | required | Field whose value is the {value} part of the folder path |
uploads.max_mb | 100 | Largest file, in MB, uploaded to the asset library (1–2048) |
uploads.editor_max_mb | 25 | Largest image, in MB, uploaded in the editor (1–2048) |
uploads.zip_max_mb | 500 | Largest total size, in MB, of the files in one “Download as ZIP” from the asset library (1–10240) |
uploads.zip_max_files | 500 | Most files in one “Download as ZIP” from the asset library (1–5000) |
uploads.types | 22 types | File extensions allowed in the asset library; code types are refused |
Page: Images and uploads.
Lists
| Key | Default | What it does |
|---|---|---|
lists.page_sizes | [10, 20, 50, 100, 200] | Rows per page offered (5–500, at most 10 choices) |
lists.page_size | 50 | Rows per page until the user picks another (one of page_sizes) |
lists.asset_page_size | 50 | Items per page in the asset library (one of page_sizes) |
lists.default_columns | 5 | Columns a list without chosen columns shows, name and built-in columns included (at most max_columns when that is set; not set: 5, or max_columns when smaller) |
lists.max_columns | 0 | Most field columns admins or users may pick for a list (0–100); 0 = no limit, everyone decides. The name, Assigned to, Changed and Publication are not counted |
sort_indexes.on_cache_warmup | false | true: cache:clear and cache:warmup also add missing sort indexes of big lists (an ALTER TABLE on big tables, during the deploy). false: only keel:sort-indexes does |
list_limit | 1000 | Most objects held in the browser at once (1–20,000): a tree list with more is shown flat and paged on the server |
page_threshold | 150 | Lists with more objects than this are paged on the server (at most list_limit) |
relation_option_limit | 500 | Most choices in the dropdown for linked objects |
Page: Lists and big lists.
The list API's cols parameter only accepts columns the list offers. A workflow's marking field changes only through the workflow's steps (Workflows).
Statuses
| Key | Default | What it does |
|---|---|---|
statuses.colors.new | '#2563eb' | Colour of new / open statuses |
statuses.colors.progress | '#0891b2' | Colour of in-progress statuses |
statuses.colors.closed | '#52525b' | Colour of done / closed statuses |
statuses.colors.rejected | '#e11d48' | Colour of rejected / cancelled statuses |
statuses.palette | 5 colours | Colours for statuses without a meaning, in option order (1–20) |
statuses.words.new | [] | Your words meaning new / open |
statuses.words.progress | [] | Your words meaning in progress |
statuses.words.closed | [] | Your words meaning done / closed |
statuses.words.rejected | [] | Your words meaning rejected / cancelled |
Page: Statuses.
Who works on what
| Key | Default | What it does |
|---|---|---|
assignments.classes.<Class>.status_field | ~ | Select or text field whose changes are logged with who / when |
assignments.classes.<Class>.roles | [] (all) | Role names or IDs that can be picked |
assignments.notify | true | Send the assignee a Pimcore notification |
Page: Assignments.
Search
| Key | Default | What it does |
|---|---|---|
search.index | auto | auto: Pimcore's search index when installed and up to date; off: always the database |
search.max_queue | 1000 | More waiting changes than this: the index counts as out of date |
Page: Search.
Keel page check
| Key | Default | What it does |
|---|---|---|
page_check.enabled | true | false hides Keel page check |
page_check.title.min | 15 | Shorter page titles get a warning |
page_check.title.max | 60 | Longer page titles get a warning |
page_check.description.min | 70 | Shorter meta descriptions get a warning |
page_check.description.max | 160 | Longer meta descriptions get a warning |
page_check.wcag | 2.1-AA | 2.0-A, 2.0-AA, 2.1-AA or 2.2-AA |
page_check.skip | [] | Checks to leave out, by id (all ids) |
page_check.vague_link_texts | [] | Link texts that say nothing, added to the built-in ones |
page_check.speed.render_ms.warning | 800 | Server time, ms: above is a warning |
page_check.speed.render_ms.error | 2000 | Server time, ms: above is an error |
page_check.speed.html_kb | 200 | Largest HTML size, in kB |
page_check.speed.weight_mb.warning | 3.0 | Page weight, MB: above is a warning |
page_check.speed.weight_mb.error | 6.0 | Page weight, MB: above is an error |
page_check.speed.requests | 80 | Most files a page loads |
page_check.timeout_s | 20 | Seconds a check waits for the page (5–120) |
page_check.history | 10 | Results kept per page for the trend (1–100) |
page_check.stale_days | 7 | Days after which a Site check result counts as old (1–365) |
page_check.pagespeed_link | true | Offer Open in PageSpeed Insights |
page_check.robots_property | ~ | Document property holding noindex; empty = try the usual names |
Page: Keel page check.
History
| Key | Default | What it does |
|---|---|---|
history.keep | 50 | Changes kept per user in Setup → History (10–500); older ones are removed. The page shows the last 10 with Show more. Changes made in Pimcore's own admin are not listed |
Interface
| Key | Default | What it does |
|---|---|---|
languages.available | [en, hr, de] | Languages users can pick |
languages.default | ~ | Language until a user picks one; empty = their Pimcore account language |
tour.auto_start | true | Start the first-time tour by itself once, on each user's first visit; false = only when a user starts it (the ? button in Keel’s header → Take the tour) |
cache.counts_ttl | 60 | Seconds item counts of big lists, status tabs and menu counts are remembered (0–3600; 0 = count every time) |
export.max_rows | 100000 | Most rows one export may have (1–1,000,000); a bigger one asks the user to narrow the list first |
export.direct_rows | 2000 | Up to this many rows the file is made in the request and downloads at once (0–100,000); a bigger export runs as a job on the server (with bulk.server_jobs on) and goes on when the page is closed |
export.keep_hours | 72 | Hours the file of an export job can be downloaded from Setup → Bulk jobs (1–8,760) |
import.max_rows | 10000 | Most rows one file may have (1–200,000) |
import.max_file_mb | 20 | Largest file, in MB (1–200); PHP's upload_max_filesize and post_max_size must allow it |
bulk.server_jobs | true | Bulk changes of more than 20 items run as a job on the server. false: they run in the browser tab in batches of 20, and Select all matching stops at 20,000 |
bulk.max_items | 200000 | Most items one bulk job may change (1–2,000,000); a bigger one asks the user to narrow the list first |
bulk.batch_size | 50 | Items a job works on before the worker turns to its other queues (1–500; a batch also ends after 20 seconds) |
bulk.max_active_per_user | 3 | Bulk jobs one user can have running or waiting at the same time (1–50) |
bulk.keep_days | 30 | Days a finished job and its per-item report are kept (1–3650) |
bulk.transport | pimcore_generic_execution_engine | Messenger transport for bulk jobs; your worker must consume it. Put it last in messenger:consume, so that it does not hold up other queues. If it does not exist, Keel uses pimcore_core |
completeness.enabled | true | false: no Completeness page, column, filter, badge or card, whatever rules are stored |
completeness.batch_size | 1000 | Items scored per query in a recalculation (50–5000); rules naming a block, field collection or brick read 100 at a time through the object |
Page: Interface languages.
Environment
| Variable | Default | What it does |
|---|---|---|
KEEL_LICENSE_KEY | none | The licence key: unlocks Keel. In .env.local or the server, never in git. Licence |
Fixed in code
These values are the same in every project. They are listed so you know them, not to change them.
| What | Value |
|---|---|
| Keel page check points off | problem 15, warning 6, tip 2; accessibility by axe impact: critical 15, serious 10, moderate 5, minor 2 |
| Keel page check LCP / CLS | 2.5 s / 4 s and 0.1 / 0.25 (warning / error); counted only when more than 10 % (LCP, server time) or 0.01 (CLS) over |
| Site check trend | arrows from a change of 3 points |
| Oversized image | wider than 600 px and more than twice its shown size |
| Lazy loading | images more than 1.5 screens down should load lazily |
| Check frame | 1366 × 900 (desktop) |
| Page weighing | at most 150 files, 6 at a time, 8 s, 25 MiB |
| Stored findings per check | 200 |
| Bulk changes | up to 20 items in one request; more as a job on the server (bulk.*) |
| Asset bulk actions | delete / move: sent 50 files at a time (the server takes at most 500 per request); Select all in a list, folder or search up to 5,000 files |
| Download as ZIP | at most 2 ZIPs per user wait for download (older ones are removed); ZIPs not downloaded within 1 hour are removed; all waiting ZIPs together at most 4 × uploads.zip_max_mb (at least 1 GB) |
| Search index | with 10,000 or more hits the database is used; items saved in the last 5 minutes are always found through the database |
| Being edited by | shown for 60 s after the last sign of life; the editor reports every 20 s |
| History | an item's saved versions: the last 20 saves. Setup → History: 10 per page; a revert of more than 100 items runs as a job on the server; a revert covers at most the first 5,000 items of a change |
| Overview cards | Recently edited 12, Not published and Assigned to me up to 50 (the card shows what fits, Show all the rest), Following 30 |
| Assignments | notes up to 5,000 characters; Activity shows up to 200 entries |
| Customize | up to 20 saved theme presets; names up to 80 characters |
| Data model field tweaks | label up to 80, help text up to 400 characters |
| Scripts & tracking | up to 50,000 characters per box |
| Menu | 264 px wide, resizable from 200 to 360 px |
| Touch layout | below 1100 px screen width |
| Header switcher | always offers All and starts on it (not configurable yet) |
| Classic admin | Keel opens as the first tab (not configurable yet) |
| Customize and Scripts | only Pimcore administrators see them (not configurable yet) |
| Theme presets | made and saved only in Customize, not in keel.yaml |
| Keel page check / Site check | fetching a page's source gives up after 30 s (page_check.timeout_s is the wait for the page to load) |
| List search typo tolerance | with the search index, words of 4 or more letters also match with one typo |
The full example file
The bundle's config/keel.example.yaml, as it ships:
# keel.yaml reference: every key with its default. Copy only what you change into config/packages/keel.yaml.
# Entries under <css-var>, <pattern>, <Class> and <list-key> are examples (Keel ignores them): write one per colour, folder, class or list.
# More: Keel docs → Setup → keel.yaml reference, and bin/console config:dump-reference keel
keel:
# ── Look ──
# Tab and header title
title: Dashboard
# Smaller text under the title in the header
subtitle: 'Content dashboard'
# Image URL shown in the header
logo: ~
# Address of the website, for the "Website" link in the header
website_url: /
# Interface colours: name => colour, e.g. accent: "#0066A5" (buttons) or grad: "linear-gradient(90deg, #0066A5, #2BABE2)"; the names are those of Keel's stylesheet (CSS variables without "--")
theme:
'<css-var>': '#0066A5'
# ── Content ──
# Which data object classes get an automatic list
classes:
# Class names to show; empty = all
include: []
# Class names to hide
exclude: []
# Lists in the menu: list key => settings. The key of an automatic list is its class name in lower case with dashes (SpecialOffer: special-offer) and changes that list; a new key adds a list
collections:
'<list-key>':
# Class name; optional when overriding an automatic list
class: ~
# false hides the list
enabled: true
# List name in the menu (default: the class title)
title: ~
# Name of one item, for "+ New …" (default: the title)
singular: ~
# Menu icon name (default: the class icon)
icon: ~
# Menu group the list is shown under
group: ~
# Show only some objects of the class: a database condition on its fields, e.g. type = "cruise"
condition: ~
# Parent folder of new objects
folder: ~
# Field used as the row / item label
label: ~
# Field names shown as table columns, in order (at most lists.max_columns, when set); without them a list shows lists.default_columns columns
columns: []
# Field the list is sorted by
order_by: ~
# Sort order: ASC (A to Z, 1 to 9) or DESC (Z to A, 9 to 1)
order: ~
# Field values for new objects
defaults: {}
# Select field shown as coloured status chips and Open / Closed tabs (default: the assignments status_field, else a select field named "status"); an admin's choice in Customize → Statuses wins over it
status_field: ~
# Header switcher, e.g. markets: objects under a path of another option are hidden
scope:
# Name of the switcher, shown in each option's tooltip
label: Market
# The choices: key => {label, short, locale}, e.g. de: {label: German, short: DE, locale: de_DE}; short = button text (default: the key in capitals); any other value, e.g. site: 2, can be used in urls as {scope.site}
options: {}
# Object paths per option, e.g. /Products/{scope}/
paths: []
# Website page per class, for "View on website" and the live preview, e.g. Product: '/products/{slug}'
urls:
'<Class>':
# Path with placeholders: {id}, {key}, {locale}, {scope}, {scope.<name>}, {<field>}
path: '/products/{slug}'
# Pimcore site id (or a placeholder such as {scope.site}); its main domain makes the public URL
site: ~
# Public domain instead of a site, e.g. https://shop.example.com or {scope.domain}
domain: ~
# Preview only published objects (the site serves only those)
published_only: true
# ── Images & uploads ──
# Asset folder for images uploaded in the editor
upload_folder: /dashboard-uploads
# Asset folder the image picker searches
image_folder: /
# Name asset folders after objects: "/product-photos/{value}" => {class: Product, field: sku}; the library also opens there for that object
folder_labels:
'<pattern>':
# Class of the objects the folders belong to
class: Product
# Field whose value is the {value} part of the folder path
field: sku
# Files uploaded in Keel (the server's PHP settings upload_max_filesize and post_max_size must allow the same size)
uploads:
# Largest file, in MB, uploaded to the asset library
max_mb: 100
# Largest image, in MB, uploaded in the editor
editor_max_mb: 25
# Largest total size, in MB, of the files in one "Download as ZIP" from the asset library
zip_max_mb: 500
# Most files in one "Download as ZIP" from the asset library
zip_max_files: 500
# File extensions that can be uploaded to the asset library; types that can run code are refused. SVG files are cleaned on upload (scripts, links and outside files are removed; what cannot be checked, and svgz, is refused)
types: [jpg, jpeg, png, webp, avif, gif, svg, mp4, webm, mov, mp3, wav, pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip]
# ── Lists ──
# Object and asset lists
lists:
# Rows per page offered under a list (5–500, at most 10 choices)
page_sizes: [10, 20, 50, 100, 200]
# Rows per page of an object list until the user picks another (one of page_sizes)
page_size: 50
# Items per page in the asset library (one of page_sizes)
asset_page_size: 50
# Most field columns admins or users may pick for a list (the name, Assigned to, Changed and Publication not counted); 0 = no limit, everyone decides
max_columns: 0
# Columns a list without chosen columns shows, the name and built-in columns included (at most max_columns when that is set; not set: 5, or max_columns when smaller)
default_columns: 5
# Most objects held in the browser at once: a tree list with more is shown flat and paged on the server
list_limit: 1000
# Lists with more objects than this are paged on the server (at most list_limit)
page_threshold: 150
# Most choices offered in the dropdown for picking linked objects (relation fields)
relation_option_limit: 500
# ── Statuses ──
# Default colours and words of list statuses (Customize can still change them per list)
statuses:
# Colour per kind of status, as #rrggbb: set the light theme colour, Keel works out the dark theme shade and the text colour
colors:
# Colour of new / open statuses
new: '#2563eb'
# Colour of in progress statuses
progress: '#0891b2'
# Colour of done / closed statuses
closed: '#52525b'
# Colour of rejected / cancelled statuses
rejected: '#e11d48'
# Colours, #rrggbb, for statuses without a meaning, in option order (1–20)
palette: ['#059669', '#4f46e5', '#0d9488', '#475569', '#65a30d']
# Option values or labels that mean new / in progress / closed / rejected, added to the built-in English, Croatian and German words
words:
# Words meaning new / open
new: []
# Words meaning in progress
progress: []
# Words meaning done / closed
closed: []
# Words meaning rejected / cancelled
rejected: []
# ── Who works on what ──
# Assign items to a Pimcore user or role, per class, e.g. classes: {Enquiry: {status_field: status}}; classes not listed get nothing new
assignments:
# Class name => its assignment settings ("Enquiry: ~" for none)
classes:
'<Class>':
# Select or text (input) field whose changes are logged with who / when (optional)
status_field: ~
# Role names or IDs that can be picked; empty = all roles
roles: []
# Send the assignee a Pimcore notification when an item is assigned to them
notify: true
# ── Completeness ──
# Completeness scores: the rules themselves are set in Setup → Settings → Completeness
completeness:
# false: no Setup page, column, filter, badge or card, whatever rules are stored
enabled: true
# Items scored per query in a recalculation (rules naming a block, field collection or brick read 100 at a time through the object)
batch_size: 1000
# ── Search ──
# List search
search:
# auto: search lists with Pimcore's search index when it is installed and up to date; off: always search the database directly
index: auto
# The search index counts as out of date when more changes than this are waiting to be added to it
max_queue: 1000
# ── Page check ──
# Keel page check in Documents (SEO, accessibility, speed, good practice)
page_check:
# false hides Keel page check
enabled: true
# Recommended page title length, in characters
title:
# Shorter gets a warning
min: 15
# Longer gets a warning
max: 60
# Recommended meta description length, in characters
description:
# Shorter gets a warning
min: 70
# Longer gets a warning
max: 160
# Accessibility standard checked (WCAG version and level): 2.0-A, 2.0-AA, 2.1-AA or 2.2-AA
wcag: 2.1-AA
# Checks to leave out, by id, e.g. seo-og-image, or axe:color-contrast for an accessibility rule; all ids: Keel docs → Setup → keel.yaml reference
skip: []
# Link texts that say nothing, added to the built-in ones (click here, read more, više, mehr …)
vague_link_texts: []
# Speed limits
speed:
# Time the server takes to build the page, in ms: above warning is a warning, above error an error
render_ms:
# Warning limit
warning: 800
# Error limit
error: 2000
# Largest size of the page's HTML, in kB
html_kb: 200
# Total size of everything the page loads, in MB: above warning is a warning, above error an error
weight_mb:
# Warning limit
warning: 3.0
# Error limit
error: 6.0
# Most files a page loads
requests: 80
# Seconds a check waits for the page to load
timeout_s: 20
# Results kept per page for the trend
history: 10
# Days after which a Site check result counts as old
stale_days: 7
# Offer "Open in PageSpeed Insights" for public https pages
pagespeed_link: true
# Document property that holds the robots (noindex) setting; leave empty (~) to try robots, meta_robots, seo_robots, noindex and seo_noindex
robots_property: ~
# ── History ──
# Setup → History: the last changes each user made in Keel, with Revert (changes made in Pimcore's own admin are not listed)
history:
# Changes kept per user (10–500); older ones are removed. The History page shows the last 10 with "Show more"
keep: 50
# ── Interface ──
# Interface languages (users pick theirs under Setup → My view; classic admin: Setup → Language)
languages:
# Languages users can pick: en, hr, de
available: [en, hr, de]
# Language until a user picks one; leave empty (~) to use the language of the user's Pimcore account
default: ~
# The first-time guided tour: it points out where things are in Keel (anyone can start it again from the ? button in Keel’s header)
tour:
# Start the tour by itself once, on each user's first visit; false = only when a user starts it
auto_start: true
# ── Cache ──
# How long Keel remembers values that take time to work out
cache:
# Seconds item counts of big lists, status tabs and menu counts are remembered; 0 = count every time
counts_ttl: 60
# ── Sort indexes ──
# Database indexes big lists sort by (keel_s_* on the classes' query tables). They are added by bin/console keel:sort-indexes, a deploy step
sort_indexes:
# true: cache:clear and cache:warmup also add missing sort indexes (an ALTER TABLE on big tables, during the deploy). false: only the command does
on_cache_warmup: false
# ── Export ──
# Export of lists to CSV and Excel (the Export button above every list)
export:
# Most rows one export may have; a bigger one asks the user to narrow the list first
max_rows: 100000
# Up to this many rows the file is made in the request and downloads at once; a bigger export runs as a job on the server (with bulk.server_jobs on) and goes on when the page is closed
direct_rows: 2000
# Hours the file of an export job can be downloaded from Setup → Bulk jobs
keep_hours: 72
# Taking an exported file back into a list: the Export / Import panel's Import changes
import:
# Most rows one file may have
max_rows: 10000
# Largest file, in MB; PHP's upload_max_filesize and post_max_size must allow it
max_file_mb: 20
# Bulk changes on a list: more than 20 items run as a job on the server
bulk:
# false: bulk changes run in the browser tab in batches of 20, and Select all matching stops at 20,000
server_jobs: true
# Most items one bulk job may change; a bigger one asks the user to narrow the list first
max_items: 200000
# Items a job works on before the worker turns to its other queues (a batch also ends after 20 seconds)
batch_size: 50
# Bulk jobs one user can have running or waiting at the same time
max_active_per_user: 3
# Days a finished job and its per-item report are kept
keep_days: 30
# Messenger transport for bulk jobs; your worker must consume it. Put it last in messenger:consume, so that it does not hold up other queues
transport: pimcore_generic_execution_engine