view release on metacpan or  search on metacpan

bin/karr  view on Meta::CPAN

    # replacing the accidental 255 an uncaught die used to leak.
    #
    # Usage-error dies carry one of these stable leading markers:
    #   "Unknown command:"          the dispatch guard in App::karr
    #   "unexpected extra argument"  surplus positionals (Role::CliArgs)
    #   "Usage:"                     a missing required positional
    # Any new usage-error die must start with one of these. Everything else --
    # task not found, board missing, a Git/sync failure, a refused destructive
    # operation -- is a runtime failure (1).
    #
    # Option-parse errors (unknown option, invalid option value) never reach
    # here: MooX::Options exits 2 directly via App::karr::Role::ExitCodes (and
    # the root's _print_help), so those exits bypass this eval.
    my $is_usage = defined $err
        && $err =~ /\A(?:Unknown command:|unexpected extra argument|Usage:)/;

    print STDERR $err if defined $err && length $err;
    exit( $is_usage ? 2 : 1 );
}

__END__

=pod

=encoding UTF-8

=head1 NAME

karr - Kanban Assignment & Responsibility Registry

=head1 VERSION

version 0.400

=head1 SYNOPSIS

    karr init --name "My Project"
    karr create "Fix login bug" --priority high
    karr move 1 in-progress --claim swift-fox
    karr board
    karr backup > karr-backup.yml

=head1 DESCRIPTION

F<karr> is the primary command line interface for L<App::karr>. It manages a
Git-native kanban board whose canonical state lives in C<refs/karr/*>, plus
optional helper payloads in non-protected refs outside that namespace.

Run it from inside a Git repository. Commands discover the repository root,
pull the current board refs, materialize a temporary board view for the command
run, and then write changes back to Git refs. In normal use this means you can
interact with shared task state without checking a persistent F<karr/>
directory into the work tree.

The script is the best starting point when you want to understand the CLI as a
user. For architecture notes, Docker background, and Perl-facing examples, see
L<App::karr>.

=head1 CLI WORKFLOW

A typical session looks like this:

=over 4

=item 1.

Create the board once with L<App::karr::Cmd::Init>.

=item 2.

Add and inspect tasks with L<App::karr::Cmd::Create>,
L<App::karr::Cmd::List>, L<App::karr::Cmd::Show>, and
L<App::karr::Cmd::Board>.

=item 3.

Progress work with L<App::karr::Cmd::Move>, L<App::karr::Cmd::Edit>,
L<App::karr::Cmd::Pick>, and L<App::karr::Cmd::Handoff>.

=item 4.

Export, restore, or remove board state with L<App::karr::Cmd::Backup>,
L<App::karr::Cmd::Restore>, and L<App::karr::Cmd::Destroy>.

=back

=head1 COMMANDS

=head2 Board Setup And Configuration

=over 4

=item * L<App::karr::Cmd::Init>

Creates the initial board in C<refs/karr/*> and can install the bundled
project skill for Claude Code.

=item * L<App::karr::Cmd::Config>

Shows or updates writable board settings such as the board name, defaults, and
claim timeout.

=item * L<App::karr::Cmd::Context>

Generates a compact board summary for embedding into files such as F<AGENTS.md>.

=item * L<App::karr::Cmd::Skill>

Installs, checks, updates, or prints the bundled skill file for Claude Code,
Codex, and Cursor.

=back

=head2 Task Lifecycle

=over 4

=item * L<App::karr::Cmd::Create>

Creates a new task card.