/ 
App-karr-0.600
/ App::karr::Cmd::Dashboard

NAME

App::karr::Cmd::Dashboard - Multi-board overview of every karr board under a directory tree

VERSION

version 0.600

SYNOPSIS

karr dashboard
karr dashboard ~/projects
karr dashboard ~/projects --depth 2
karr dashboard --hide-no-board
karr dashboard --show-no-board
karr dashboard --json
karr dashboard --compact

DESCRIPTION

Walks a directory tree looking for Git repositories (a .git marker), checks each one for a karr board (refs/karr/config), and prints a compact, multi-column overview: one visual entry per repository, a bar of one block per open task coloured by status, arranged side by side across the terminal width rather than stacked one per line. It answers one question -- where is work sitting, right now, across every board under here -- and touches nothing: it never fetches, pushes, or writes to any board.

This is deliberately not App::karr::Foundation::Overview (karr-foundation --status): that reads a fleet configuration and reports what agents are doing. This command needs no configuration at all -- it finds what is there and shows only where tickets are.

Only open work is drawn: any status the board's own configuration marks terminal (its own last status, or archived -- see App::karr::Config, ticket #67) is left out of the bar and out of the per-board open count, the same way App::karr::Cmd::Board leaves finished work out of its default view. Status names and which one is terminal are read from each board's own config, never assumed -- two boards shown side by side may use entirely different status lists.

SEARCH

The optional positional PATH is the starting directory (default: the current directory). From there the search is recursive: any directory carrying a .git entry counts as a repository and is not searched any further (no diving into a repository's own working tree, and .git itself is never entered). --depth bounds how many directory levels below PATH are descended into (default 4) -- unbounded would never finish under a home directory. Symlinked directories are never followed, to avoid loops; a directory that cannot be read (permissions) is skipped rather than aborting the whole scan.

That positional PATH is the only way to name the scan root. The root option --dir -- which every board command accepts in either placement, karr --dir PATH list as well as karr list --dir PATH -- is refused here in both placements, and both exit 2: karr dashboard --dir PATH is an unknown option, printed with the usage line that names the positional PATH, and karr --dir PATH dashboard is refused with a message saying where the scan root goes. It is refused rather than accepted as a synonym because it does not mean the same thing: --dir is the seed of a search upward for the root of one repository (which is why it may name any directory inside that repository), while this command searches downward for every board underneath a directory. Handed one and the same path, the two would answer about different directories. There is consequently no precedence rule for karr --dir A dashboard B: it is a usage error (exit 2), not a contest the positional wins. Before ticket #225 the root placement was accepted and then discarded without a word, so the command described the current directory while looking like it had answered about the given one.

OPTIONS

  • --depth N

    Maximum recursion depth below PATH (default 4). 0 checks only PATH itself.

  • --hide-no-board

    Omit the list of repositories that have no karr board entirely, including the no_board key under --json. Wins over --show-no-board.

  • --show-no-board

    Always list the board-less repositories by name, wrapping over as many lines as it takes. Without it, a list too long for one line collapses to a count (No board: 46 repos (--show-no-board to list them)) so it cannot bury the summary line beneath it; a list that fits on one line is always shown in full and needs no flag either way.

  • --json

    Emits a structured document instead: { root, summary, boards, no_board }. Never coloured.

  • --compact

    One plain line per repository (name, a tab, then either no-board or a comma-separated list of status:count tokens ending in blocked:count), for scripts and greps. Never coloured.

SEE ALSO

karr, App::karr, App::karr::Cmd::Board, App::karr::Foundation::Overview

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)