Skip to main content
Keel Docs Showcase

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 keel prints the same options, each with a one-line explanation.
  • The bundle's config/keel.example.yaml has every key with its default (copied at the end of this page).
  • A wrong value stops bin/console cache:clear with 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

KeyDefaultWhat it does
titleDashboardTab and header title
subtitleContent dashboardSmaller 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>noneInterface colour or value per theme variable, e.g. accent: '#0066A5'. All names: Name, logo and colours

Content

KeyDefaultWhat 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>.enabledtruefalse hides the list
collections.<list-key>.titlethe class titleList name in the menu
collections.<list-key>.singularthe titleName of one item, for "+ New …"
collections.<list-key>.iconthe class iconMenu icon
collections.<list-key>.groupthe class groupMenu 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>.labelautomaticField 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.labelMarketName 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>.pathrequiredWebsite 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_onlytruePreview only published objects

Pages: Content, Header switcher, Website pages.

Images and uploads

KeyDefaultWhat it does
upload_folder/dashboard-uploadsAsset folder for images uploaded in the editor
image_folder/Asset folder the image picker searches
folder_labels.<pattern>.classrequiredClass of the objects the folders belong to; pattern e.g. /product-photos/{value}
folder_labels.<pattern>.fieldrequiredField whose value is the {value} part of the folder path
uploads.max_mb100Largest file, in MB, uploaded to the asset library (1–2048)
uploads.editor_max_mb25Largest image, in MB, uploaded in the editor (1–2048)
uploads.zip_max_mb500Largest total size, in MB, of the files in one “Download as ZIP” from the asset library (1–10240)
uploads.zip_max_files500Most files in one “Download as ZIP” from the asset library (1–5000)
uploads.types22 typesFile extensions allowed in the asset library; code types are refused

Page: Images and uploads.

Lists

KeyDefaultWhat it does
lists.page_sizes[10, 20, 50, 100, 200]Rows per page offered (5–500, at most 10 choices)
lists.page_size50Rows per page until the user picks another (one of page_sizes)
lists.asset_page_size50Items per page in the asset library (one of page_sizes)
lists.default_columns5Columns 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_columns0Most 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_warmupfalsetrue: 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_limit1000Most objects held in the browser at once (1–20,000): a tree list with more is shown flat and paged on the server
page_threshold150Lists with more objects than this are paged on the server (at most list_limit)
relation_option_limit500Most 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

KeyDefaultWhat 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.palette5 coloursColours 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

KeyDefaultWhat 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.notifytrueSend the assignee a Pimcore notification

Page: Assignments.

KeyDefaultWhat it does
search.indexautoauto: Pimcore's search index when installed and up to date; off: always the database
search.max_queue1000More waiting changes than this: the index counts as out of date

Page: Search.

Keel page check

KeyDefaultWhat it does
page_check.enabledtruefalse hides Keel page check
page_check.title.min15Shorter page titles get a warning
page_check.title.max60Longer page titles get a warning
page_check.description.min70Shorter meta descriptions get a warning
page_check.description.max160Longer meta descriptions get a warning
page_check.wcag2.1-AA2.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.warning800Server time, ms: above is a warning
page_check.speed.render_ms.error2000Server time, ms: above is an error
page_check.speed.html_kb200Largest HTML size, in kB
page_check.speed.weight_mb.warning3.0Page weight, MB: above is a warning
page_check.speed.weight_mb.error6.0Page weight, MB: above is an error
page_check.speed.requests80Most files a page loads
page_check.timeout_s20Seconds a check waits for the page (5–120)
page_check.history10Results kept per page for the trend (1–100)
page_check.stale_days7Days after which a Site check result counts as old (1–365)
page_check.pagespeed_linktrueOffer Open in PageSpeed Insights
page_check.robots_property~Document property holding noindex; empty = try the usual names

Page: Keel page check.

History

KeyDefaultWhat it does
history.keep50Changes 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

KeyDefaultWhat 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_starttrueStart 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_ttl60Seconds item counts of big lists, status tabs and menu counts are remembered (0–3600; 0 = count every time)
export.max_rows100000Most rows one export may have (1–1,000,000); a bigger one asks the user to narrow the list first
export.direct_rows2000Up 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_hours72Hours the file of an export job can be downloaded from Setup → Bulk jobs (1–8,760)
import.max_rows10000Most rows one file may have (1–200,000)
import.max_file_mb20Largest file, in MB (1–200); PHP's upload_max_filesize and post_max_size must allow it
bulk.server_jobstrueBulk 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_items200000Most items one bulk job may change (1–2,000,000); a bigger one asks the user to narrow the list first
bulk.batch_size50Items 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_user3Bulk jobs one user can have running or waiting at the same time (1–50)
bulk.keep_days30Days a finished job and its per-item report are kept (1–3650)
bulk.transportpimcore_generic_execution_engineMessenger 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.enabledtruefalse: no Completeness page, column, filter, badge or card, whatever rules are stored
completeness.batch_size1000Items 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

VariableDefaultWhat it does
KEEL_LICENSE_KEYnoneThe 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.

WhatValue
Keel page check points offproblem 15, warning 6, tip 2; accessibility by axe impact: critical 15, serious 10, moderate 5, minor 2
Keel page check LCP / CLS2.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 trendarrows from a change of 3 points
Oversized imagewider than 600 px and more than twice its shown size
Lazy loadingimages more than 1.5 screens down should load lazily
Check frame1366 × 900 (desktop)
Page weighingat most 150 files, 6 at a time, 8 s, 25 MiB
Stored findings per check200
Bulk changesup to 20 items in one request; more as a job on the server (bulk.*)
Asset bulk actionsdelete / 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 ZIPat 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 indexwith 10,000 or more hits the database is used; items saved in the last 5 minutes are always found through the database
Being edited byshown for 60 s after the last sign of life; the editor reports every 20 s
Historyan 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 cardsRecently edited 12, Not published and Assigned to me up to 50 (the card shows what fits, Show all the rest), Following 30
Assignmentsnotes up to 5,000 characters; Activity shows up to 200 entries
Customizeup to 20 saved theme presets; names up to 80 characters
Data model field tweakslabel up to 80, help text up to 400 characters
Scripts & trackingup to 50,000 characters per box
Menu264 px wide, resizable from 200 to 360 px
Touch layoutbelow 1100 px screen width
Header switcheralways offers All and starts on it (not configurable yet)
Classic adminKeel opens as the first tab (not configurable yet)
Customize and Scriptsonly Pimcore administrators see them (not configurable yet)
Theme presetsmade and saved only in Customize, not in keel.yaml
Keel page check / Site checkfetching a page's source gives up after 30 s (page_check.timeout_s is the wait for the page to load)
List search typo tolerancewith 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:

yaml
# 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