toggl-cli

Unofficial CLI for Toggl Track written in Rust, using the v9 API.

Usage

Building the binary.

cargo build # or cargo build --release

Installing the binary.

From crates.io

cargo install toggl

From Arch Linux aur

toggl-cli is available on the AUR:

• toggl-cli (release package)
• toggl-cli-bin (binary release package)

You can install it using your AUR helper of choice.

Example:

$ yay -Sy toggl-cli

From source

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

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.

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 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.

$ toggl help
toggl 0.4.9
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.

$ toggl help start
toggl-start 0.4.9
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

cargo test

Linting

Common lint tools

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 for more details.

Releasing

To create a new release, first bump the package version. We have a handy script at 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 page.

Built by the Watercooler Studio