boat-cli 0.2.0

Basic Opinionated Activity Tracker, a command line interface inspired by bartib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

# ⛵ boat

`boat` - A **B**asic **O**pinionated **A**ctivity **T**racker, inspired by [bartib](https://github.com/nikolassv/bartib).

This is only the code for the command line application. It relies on [`boat-lib`](https://github.com/coko7/boat-lib) for core functions.

[![Crates info](https://img.shields.io/crates/v/boat-cli.svg)](https://crates.io/crates/boat-cli)
[![License: GPL-3.0](https://img.shields.io/github/license/coko7/boat-cli?color=blue)](LICENSE)
![Rust](https://img.shields.io/github/languages/top/coko7/boat-cli?color=orange)
[![Tests](https://github.com/coko7/boat-cli/actions/workflows/rust.yml/badge.svg)](https://github.com/coko7/boat-cli/actions/workflows/rust.yml)

> [!WARNING]  
> 🚧 Work in Progress
>
> This cli is actively being developed. Since it's in its early stages, things will likely break often.
> Don't use it for now.

## Why was this tool created?

The [`bartib`](https://github.com/nikolassv/bartib) cli is what inspired me to create `boat`.
It's a feature-full tool that I used for a while, but I found it quite limiting for my usage due to its [lack of support for machine-readable output](https://github.com/nikolassv/bartib/pull/26).
That's it, I wanted an activity tracker that I could combine easily with [`jq`](https://github.com/jqlang/jq) and so I decided to make my own tool.

## How is `boat` intended to be used?

First, I would like to share my view on command line tools. To me, they are two types of CLIs:
- The ones meant to be invoked manually from your prompt: `cat/bat`, `vim`, `zoxide`, `rg`, etc.
    - a subcategory of those include **Terminal User Interfaces** (TUIs) like `lazygit`, `gh-dash` and many others
- And the ones meant to be used in scripts: `jq`, `fzf`, `find`

> [!NOTE]
> These examples are probably not the best ones, there is a lot of overlap between the manual/scripting.
> But a good example of this distinction are the two ways to define command line arguments:
> - short: `-j` (to use when you invoke the CLI from your prompt)
> - verbose: `--json` (to use in scripts for better read experience)

I like the idea of designing a CLI to do most of the heavy lifting (core functionalities) and do not prioritize the UI much as I would rather let the users create their own scripts and focus on making it as easy as possible for them to integrate the CLI in them.
That's why I have designed `boat` to be 'script-friendly' first, while also making sure it's okay as a tool that you invoke from the command line directly.
I think `boat` is okay as a CLI that invoke directly from your prompt but it shines best if you wrap it with custom bash scripts.

I have been using the bartib project for some time. Since it runs in the terminal, it fits with my workflow.
But as I find myself wanting to create a lot of customized keybinds and bash scripts with fzf or jq, I stumbled upon this PR: https://github.com/nikolassv/bartib/pull/26
The maintainer of bartib shares his opinion on machine-readable output and 

## Installation

The easiest way to install is through [crates.io](https://crates.io/crates/boat-cli):
```sh
cargo install boat-cli
```

The other option is to build from source:
```sh
git clone https://github.com/coko7/boat-cli.git
cd boat-cli
cargo build --release
```

## Usage

To get a feel of how `boat` can be used, you can try `boat help` to get the list of commands:
```help
Basic Opinionated Activity Tracker

Usage: boat <COMMAND>

Commands:
  new     Create a new activity
  start   Start/resume an activity
  config  Manage configuration
  pause   Pause/stop the current activity
  modify  Modify an activity
  delete  Delete an activity
  get     Get the current activity
  list    List activities and tags
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
```

If you want to invoke `boat` from your command-line directly, you can make use of a variety of shorter aliases:
```help
Commands:
  new     n
  start   s, st, sail
  config  c, cfg, conf
  pause   p
  modify  m, mod
  delete  d, del
  get     g
  list    l, ls
```
I really wanted to have each command start with a different character so that I could assign a single-char alias to all of them.
That explains why some of the commands do not use a more fitting keyword.

Like `stop` would have been a better command than `pause` but since it shares the same starting charcter as the `start` command, I could not use it.
Maybe I will drop this in the future, let's see.