Skip to main content
Keel Docs Showcase

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:

bash
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 Uploads folder 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: value is 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 change max, 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

CommandWhat it does
bin/console keel:setup --checkOnly step 0. Writes nothing. Exit code 1 if anything is ✖.
bin/console keel:setup --dry-runAsks everything, then prints the file instead of writing it
bin/console keel:setup --forceAsks 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.