tanda_cli

image

Installation

You will need Crystal 1.22.0 installed. I recommend using asdf with the crystal plugin.

asdf install crystal 1.22.0

Or you can checkout this link for platform specific instructions

Then

  1. Clone the repository
  2. Run shards install
  3. Run ./scripts/build-prod.sh
  4. You now have a release build! This can be run with ./bin/tanda_cli assuming you're in the root directory of this repository

This project doesn't currently distribute to any package managers or release any binaries. I recommend aliasing if you intend on using it outside of the repo directory

alias tanda_cli="/link/to/tanda_cli/bin/tanda_cli"

Usage

Upon running any command for the first time, you will be taken through an authentication flow where you will need to enter your username and password. Your preferences are stored under ~/.config/tanda_cli/ and the retrieved token in ~/.local/share/tanda_cli/state.json (format / structure is subject to change at the moment)

See --help for a list of commands (each subcommand also accepts a --help flag)

╰─❯ tanda_cli help
A CLI application for people using Tanda/Workforce.com

Usage: tanda_cli [options] <command>

Commands:
  auth              Manage authentication
  balance           Check your leave balances
  clockin           Clock in/out
  completions       Print a shell completion script
  config            Show where the configuration lives or what it contains
  current_user      View the current user, list available users or set the current user
  leave             View your leave
  me                Get your own information
  mode              Set the mode to run commands in (production/staging/custom <url>)
  personal_details  Get your personal details
  regular_hours     View or set your regular hours
  start_of_week     Set the start of the week (e.g. monday/sunday)
  time_worked       See how many hours you've worked
  help              Show this help

Options:
      --no-colour  Disable ANSI colours
  -h, --help       Show this help

Examples

# Clock in
tanda_cli clockin start

# Set a default clockin photo to be used with clockins (can be a specific photo or directory of photos to be chosen at random)
tanda_cli clockin photo set /Users/me/Pictures/clockin_photos/my_cool_photo.png
tanda_cli clockin photo set /users/me/Pictures/clockin_photos # as a directory

# See time worked today or for the week
tanda_cli time_worked today
tanda_cli time_worked week --display # both options accept a flag to display the shifts

# See your leave
tanda_cli leave upcoming # leave booked between today and a year from now
tanda_cli leave taken    # leave taken over the past year
tanda_cli leave list --from 2026-01-01 --to 2026-06-30 --status pending
tanda_cli leave show 2026-12-25 # by date, or by leave request id

# Goes through each week of your roster to find your working hours (makes `time_worked` much more accurate)
tanda_cli regular_hours determine

# Displays your regular hours for the week
tanda_cli regular_hours display

# Set the mode to run commands in
tanda_cli mode production # this is the default mode
tanda_cli mode staging

Shell completions

tanda_cli generates completion scripts for fish, bash, and zsh. Source it at shell startup so completions always match the installed binary:

# fish (~/.config/fish/config.fish)
tanda_cli completions fish | source
# bash (~/.bashrc)
eval "$(tanda_cli completions bash)"
# zsh (~/.zshrc, after compinit)
source <(tanda_cli completions zsh)

Development

API Docs

https://my.tanda.co/api/v2

Running your changes

crystal run src/tanda_cli.cr -- <command/s>

Examples

# With debug logs enabled
crystal run src/tanda_cli.cr -- me

# Without debug logs
crystal run src/tanda_cli.cr --no-debug -- me

Contributing

  1. Clone repo
  2. Implement your idea / fix bug
  3. Make a pull request

Contributors