First configuration with keel:setup
Keel works with no configuration at all: title Dashboard, Keel's colours, one list per class, no switcher. To make it fit the project, run:
bin/console keel:setup
It first checks the install, then asks ten short questions. It suggests answers from the project itself: its folders, classes and fields. At the end it writes config/packages/keel.yaml.
How to answer
- Most questions are numbered lists. Type the number, or press Enter for the suggestion shown in
[brackets]. - Where several answers are allowed, type them with commas:
1,3. - Only names are typed (a title, a label). Every answer can be changed later in the file.
The steps
0 · Install check
- Asks: Nothing. It runs the install check. If a line is ✖, it asks Continue anyway? (default: no).
1 · Name and colours
- Asks: Title, subtitle, and a colour preset or your own accent and brand colour.
- Suggests: Dashboard, Content dashboard, Keel's colours.
- Writes:
title,subtitle,theme.accent,theme.brand
2 · Images
- Asks: Where the image picker looks, and where editor uploads go.
- Suggests: The top folder with the most images, and a new
Uploadsfolder inside it. - Writes:
image_folder,upload_folder
3 · Header switcher
- Asks: Whether to split the content by folder (markets, deal type). Then a label and content language per option, and the switcher's name.
- Suggests: Object folders with 2 to 8 subfolders.
- Writes:
scope
4 · Content classes
- Asks: Classes to hide from editors, such as imports or logs.
- Suggests: Every class, with its number of objects.
- Writes:
classes.exclude
5 · Assignments
- Asks: Which lists support "who works on what", and each one's status field.
- Suggests: A field named status, else one with status or state in its name.
- Writes:
assignments.classes(Assignments)
6 · Website pages
- Asks: Which classes have their own page on the website, and its address.
- Suggests: For classes without a link generator:
/class/{slug},/class/{key}or/class/{id}. - Writes:
urls
7 · Names
- Asks: Lists that need a name for one item: "+ New Enquiry" instead of "+ New Enquiries".
- Suggests: English singulars (Enquiries → Enquiry). In other languages you type it.
- Writes:
collections.<list-key>.singular
8 · Asset folders named after objects
- Asks: A folder with one subfolder per object, the class, and the field that names the subfolders.
- Suggests: Folders with 3 or more subfolders, and the field whose values match the most folder names.
- Writes:
folder_labels
9 · Interface languages
- Asks: Which languages users can pick, and the language until they pick one.
- Suggests: All three (en, hr, de), and each user's Pimcore account language.
- Writes:
languages(only when not the default)
10 · Keel page check
- Asks: The document property that holds noindex, and the accessibility level.
- Suggests: Properties found on your documents; WCAG 2.1-AA.
- Writes:
page_check.robots_property,page_check.wcag(only when not the default)
A step with nothing to ask is skipped with a short note, for example No document has a robots property: Keel tries them all.
Then it says: Written config/packages/keel.yaml. Run bin/console cache:clear, then open the admin.
The file it writes
The answers come first. After them, every other option is written as a comment with its default. So the file also works as a reference.
-
A line starting with
#(hash and space) is an explanation. -
A line like
#key: valueis an option you can switch on: delete the#in front of it. For an option inside a group, also delete the#of each group line above it (the lines ending in:), and keep the spaces. For example, to changemax, delete all three#:#page_check: #title: #max: 60 -
Entries named
<…>(such as'<Class>') are examples. Keel ignores them if you leave them in. Replace<…>with a real name to use one.
The header names the reference: All options: Keel docs → Setup → keel.yaml reference, or bin/console config:dump-reference keel.
Copy only what you change
You can also write keel.yaml by hand. Start from an example, or copy single keys from the bundle's config/keel.example.yaml. Keys you leave out keep their default.
Run it again
| Command | What it does |
|---|---|
bin/console keel:setup --check | Only step 0. Writes nothing. Exit code 1 if anything is ✖. |
bin/console keel:setup --dry-run | Asks everything, then prints the file instead of writing it |
bin/console keel:setup --force | Asks everything and replaces an existing keel.yaml |
Without --force, keel:setup does not touch an existing keel.yaml. It stops and suggests --check, --dry-run or --force.
--force replaces the whole file, including your own edits. To change one thing, edit the file instead, or run --dry-run and copy the lines you need.
After any change to keel.yaml, run bin/console cache:clear. If the yaml has a mistake, cache:clear fails with a message that names the key, for example keel.lists.page_size: 25 is not one of page_sizes (10, 20, 50, 100, 200).
What keel:setup does not ask
Set these in keel.yaml when you need them: logo, website_url, other collections settings (columns, conditions, extra lists), assignment roles, lists, uploads, statuses, search and the rest of page_check. Each has its page in this section.
Lists shown, columns, names, icons and colours can also be changed later by admins in Customize, without a developer.