view release on metacpan or  search on metacpan

bin/karr  view on Meta::CPAN

Replaces the current board refs from a YAML snapshot. This is intentionally
destructive and requires explicit confirmation flags.

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

Deletes the whole board namespace from the repository.

=back

=head2 Helper Refs

=over 4

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

Stores arbitrary helper payloads in allowed refs outside protected namespaces.

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

Fetches one helper ref and prints only its payload to standard output.

=back

=head1 EXIT CODES

F<karr>'s primary callers are agents scripting the CLI, for whom C<$?> is part
of the interface. The exit code is therefore a stable contract (see
F<docs/adr/0002-exit-code-contract.md>):

=over 4

=item * B<0> — success, including no-op successes such as re-archiving a task
that is already archived.

=item * B<1> — runtime failure: a task id was not found, the board is missing,
a Git or sync operation failed, a destructive command was refused for want of
C<--yes>, or a batch committed partial work but at least one item failed.

=item * B<2> — usage error: an unknown command, an unknown option, an invalid
option value, or a surplus or missing positional argument.

=back

The C<1>-versus-C<2> split is what lets a scripting agent tell "I called this
wrong" apart from "the operation failed". This deviates deliberately from
kanban-md, which exits C<1> for everything.

=head1 DOCKER USAGE

The CLI works well through the published Docker image. A common alias is:

    alias karr='docker run --rm -it -w /work -e HOME=/home/karr \
      -v "$(pwd):/work" \
      -v "$HOME/.gitconfig:/home/karr/.gitconfig:ro" \
      -v "$HOME/.claude:/home/karr/.claude" \
      -v "$HOME/.codex:/home/karr/.codex" \
      raudssus/karr:latest'

That keeps the current repository mounted at F</work> and lets the default
image adapt its runtime uid and gid to the owner of the mounted workspace. The
CLI syntax stays the same after that:

    karr board
    karr skill install --agent codex --global --force

If you prefer a fixed non-root runtime, use C<raudssus/karr:user> instead. That
image defaults to uid and gid C<1000:1000> and is intended as the predictable
base for downstream custom images. Custom fixed-user derivatives can override
C<KARR_UID> and C<KARR_GID> at build time.

=head1 EXAMPLES

Initialize a new board and install the project-local Claude Code skill:

    karr init --name "HandyIntelligence Prototype" --claude-skill

Claim and start the next task for a generated agent:

    NAME=$(karr agentname)
    karr pick --claim "$NAME" --move in-progress

Export the board before trying a destructive restore:

    karr backup > karr-backup.yml
    karr restore --yes < karr-backup.yml

=head1 SEE ALSO

L<App::karr>, L<App::karr::Task>, L<App::karr::BoardStore>,
L<App::karr::Git>, L<App::karr::Cmd::Init>, L<App::karr::Cmd::Skill>,
L<App::karr::Cmd::Backup>, L<App::karr::Cmd::Restore>

=head1 SUPPORT

=head2 Issues

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

=head2 IRC

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

=head1 CONTRIBUTING

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

=head1 AUTHOR

Torsten Raudssus <getty@cpan.org>

=head1 COPYRIGHT AND LICENSE

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

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut