Skip to content

Command Line Lint

tempus2016 edited this page Nov 9, 2026 · 2 revisions

Checking Dashboards from the Command Line (v2.9.0+)

Dashboards kept as YAML files can be checked without opening Home Assistant. The checks are the template editor's own: placeholders that cannot work, such as a misspelt step, variables read but never declared, cards passing a variable their template never reads, templates used nowhere or missing, extends: loops, and deprecated templates still in use.

The card is not published to npm, so there is no npx. The linter is a file in the card's repository, bin/dcp-lint.js, and needs nothing but Node.js:

git clone https://github.com/tempus2016/decluttering-card-plus.git
node decluttering-card-plus/bin/dcp-lint.js lint dashboards/rooms.yaml dashboards/cameras/

A directory is read for every .yaml and .yml file in it and in the folders under it. The word lint is optional. Each finding prints with its level, its line, what is wrong, and where in the dashboard:

dashboards/rooms.yaml
  warning    2  [[room|titel]]: "titel" is not a transform, a lookup or a fallback this card knows, so the placeholder will show as written.  [room_tile.card.name]
  warning    2  Cards using "room_tile" on Rooms that pass "colour", which the template never reads: 1.  [template: room_tile]
  info       2  Read here but neither declared nor given a default, so every card has to set them: light (card.entity), room (card.name).  [room_tile]
  info      10  "old_tile" is deprecated (Use room_tile instead) and still used by: Rooms (1).  [old_tile]
  info      10  Read here but neither declared nor given a default, so every card has to set them: light.  [old_tile.card.entity]
  error     25  The template "room_tlie" doesn't exist in decluttering_templates or in a custom:decluttering-template card. Did you mean "room_tile"?  [template: room_tlie]

1 error, 2 warnings, 3 info in 1 file · 0.0 s

The line is that of the template, or of the card, the finding is about; the part in brackets at the end narrows it down to the key.

Output for a pull request, or a program

Flag Prints
--format=text The lines above, the default
--format=github GitHub Actions annotations (::error file=…,line=…::), so findings show on the files of a pull request
--format=json One JSON list of findings, each with file, level, line, path, message and template, and no summary line

Exit codes

Code When
0 Nothing worse than a warning. A misspelt step is a warning: it is printed and the run still passes
1 Something is an error: a template that does not exist, an extends: loop
2 The command could not run: a path that cannot be read, no .yaml files found, or an unknown option

So a pre-commit hook or a workflow fails on what breaks a dashboard and reports the rest.

In GitHub Actions

# .github/workflows/dashboards.yml
name: Check dashboards
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/checkout@v4
        with:
          repository: tempus2016/decluttering-card-plus
          ref: v2.9.0
          path: dcp
      - run: node dcp/bin/dcp-lint.js lint --format=github dashboards/

The second checkout fetches the card's repository beside yours. Pin ref: to a release so a new version of the checks cannot fail a run you did not change.

What it cannot know

Without Home Assistant it cannot tell which entities, areas or labels exist, so a repeat that will match nothing is not reported, and the messages are always in English.

Home Assistant's own tags, !include, !secret, !include_dir_merge_list and the rest, are read without failing, but what they bring in is not followed. The summary says when it met one:

not followed: !include - what they bring in was not checked

In a file that uses one, the checks that need the whole dashboard are skipped, since part of it is somewhere else: a card pointing at a template that does not exist, or a template nothing uses, is not reported there.


→ Recipes · Visual Editors · Troubleshooting

Clone this wiki locally