toggl 0.4.11

Unofficial command-line interface for Toggl Track using the v9 API.
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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

# toggl-cli

Unofficial CLI for [Toggl Track](https://toggl.com/track/) written in Rust, using the [v9 API](https://developers.track.toggl.com/docs/).

## Usage

Building the binary.

```shell
cargo build # or cargo build --release
```

Installing the binary.

### From [crates.io](https://crates.io/crates/toggl)

```shell
cargo install toggl
```

### From Arch Linux aur
[![toggl-cli](https://img.shields.io/aur/version/toggl-cli?label=toggl-cli)](https://aur.archlinux.org/packages/toggl-cli/)
[![toggl-cli-bin](https://img.shields.io/aur/version/toggl-cli-bin?label=toggl-cli-bin)](https://aur.archlinux.org/packages/toggl-cli-bin/)

toggl-cli is available on the [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository):
- [toggl-cli](https://aur.archlinux.org/packages/toggl-cli/) (release package)
- [toggl-cli-bin](https://aur.archlinux.org/packages/toggl-cli-bin/) (binary release package)

You can install it using your [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) of choice.

Example:
```shell
$ yay -Sy toggl-cli
```

### From source

```shell
cargo install --path .
```

> This places the release optimized binary at `~/.cargo/bin/toggl`. Make sure to add `~/.cargo/bin` to your `$PATH` so that you can run the binary from any directory.

You can invoke the binary using the `toggl` command now. Alternatively you can also run the command directly using `cargo run`

```shell
cargo run [command]


# To list the last 3 time-entries
cargo run list -n 3
```

The first command you need to run is `auth` to set up your [Toggl API token](https://support.toggl.com/en/articles/3116844-where-is-my-api-token-located).

```shell
cargo run auth [API_TOKEN] # or toggl auth [API_TOKEN]
```

The API token is stored securely in your Operating System's keychain using the [keyring](https://crates.io/crates/keyring) crate.

> **Note**: On some linux environments the `keyring` store is not persistent
> across reboots. We recommend exporting the api token as `TOGGL_API_TOKEN`
> in your shell profile. The CLI will use this environment variable if it is
> set. You don't need to run the `auth` command if you have the environment
> variable set.

### Commands

Run the `help` command to see a list of available commands.

```shell
$ toggl help
toggl 0.4.11
Toggl command line app.

USAGE:
    toggl [FLAGS] [OPTIONS] [SUBCOMMAND]

FLAGS:
        --fzf        Use fzf instead of the default picker
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -C <directory>         Change directory before running the command
        --proxy <proxy>    Use custom proxy

SUBCOMMANDS:
    auth        Authenticate with the Toggl API. Find your API token at https://track.toggl.com/profile#api-token
    config      Manage auto-tracking configuration
    continue
    current
    help        Prints this message or the help of the given subcommand(s)
    list
    logout      Clear stored credentials
    running
    start       Start a new time entry, call with no arguments to start in interactive mode
    stop

```

You can also run the `help` command on a specific subcommand.

```shell
$ toggl help start
toggl-start 0.4.11
Start a new time entry, call with no arguments to start in interactive mode

USAGE:
    toggl start [FLAGS] [OPTIONS] [--] [description]

FLAGS:
    -b, --billable
    -h, --help           Prints help information
    -i, --interactive
    -V, --version        Prints version information

OPTIONS:
    -p, --project <project>    Exact name of the project you want the time entry to be associated with
    -t, --tags <tags>...       Space separated list of tags to associate with the time entry, e.g. 'tag1 tag2 tag3'

ARGS:
    <description>    Description of the time entry

```

## Testing

To run the unit-tests

```shell
cargo test
```

## Linting

Common lint tools

```shell
cargo fmt # Formatting the code to a unified style.

cargo clippy --fix # To automatically fix common mistakes.
```

The CI will also run the lint commands for all pull-requests.
See [pull_request.yml](.github/workflows/pull_request.yml) for more details.

## Releasing

To create a new release, first bump the package version.
We have a handy script at [pkg/autodoc.rs](pkg/autodoc.rs).
Running it with no arguments, bumps the current patch version, in `Cargo.toml`
and `Cargo.lock` files.
It also updates the help documentation in this README to match the current
version of the command.
Commit and push the updated changes and a new release will show up under the
[releases](https://github.com/watercooler-labs/toggl-cli/releases) page.

---

Built by the [Watercooler Studio](https://watercooler.studio/)