README.md

lightlike-cli

        

A time-tracking REPL, using Google BigQuery as a backend.

• Features
• Installation & Setup
• Command Guide

---

Features

Addtional feature videos to be added

• Aliased commands & Auto Completion.

  The primary goal of this tool is to make logging hours as fast as possible. All commands are aliased - as long as it is unique, you can type the shortest prefix down to a single character to call that command. All options have a short flag and relevant autocompletions if applicable. Previously entered notes autocomplete if their respective projects are selected as an option.

  # no options starts a new time entry under "no-project"
  $ timer run
  $ t ru
  
  $ timer run --project lightlike-cli --note "readme" --start 1h --billable true
  $ t ru -plightlike-cli -n"readme" -s1h -b1

• Concurrent timers.

  You can have multiple time entries running at once, pausing and resuming as needed.

• Export timesheet summaries.

  Export a timesheet summary as an svg/csv/json.

• BigQuery Shell.

  Write directly to BigQuery (Note: This is a very minimal feature shell, as it's not main focus of this tool).

• Backup/restore snapshots.

  Create and restore table snapshots using the bq snapshot command group.

• System commands.

  Any command not recognized by this cli will get passed to the shell.
  Configure what shell is used with command app:config:set:general:shell.

  They can also be passed by typing the command and pressing :! or esc+enter,
  or press meta+shift+1 to enable a system prompt.

  :c{1 | 2 | 3 | 4} to add/remove completions from the global completer.
  1=commands, 2=history, 3=path, 4=executables

  Path autocompletion is automatic for cd.

---

Installation & Setup

• This package is not currently hosted on PyPI. It may be uploaded in the future.
• Support for a local only version is planned long-term.

# Run the following command to install the latest release:
pip install "lightlike @ git+https://github.com/ayvi-0001/lightlike-cli@$TAG" # substitute TAG, e.g. TAG=v0.0.0

# Run the following command to install the latest commit:
pip install "lightlike @ git+https://github.com/ayvi-0001/lightlike-cli@main"

There is a short initial setup the first time the CLI runs to configure the default timezone, settings/authorization for BigQuery, and running scripts to build the required procedures/tables.

Once it's installed, start the REPL by running the command $ lightlike

Note

This tool depends on the library rtoml which is implemented in rust. When installing from your package manager , it will attempt to find the appropriate binary for your system configuration from this list. If it's it's unable to determine this, you'll need rust stable installed to compile it.

If your package manager was unable to determine your system configuration but you see an appropriate binary available, you can try to install it manually:

pip install https://files.pythonhosted.org/packages/4c/6d/48ce15a3919a5c07a19ae3c80b9fadbe1e13a5e475198143965d3de6e60b/rtoml-0.11.0-cp311-none-win_amd64.whl

Note

This CLI requires a connection to BigQuery. You must have a Google Cloud Project with billing enabled. Authorization for BigQuery can come from 2 sources:

• Environment: Application Default Credentials set using gcloud. See here for information on installing the gcloud SDK.

• Service Account Key: See here for information on creating service accounts. You'll need the role Service Account Key Admin. If you are authorizing using a service account key, this CLI will ask you to provide a password that it will use to encrypt the key. This is to avoid keeping a plain-text file of the key on the local machine.
  If you have gcloud installed, you can create a service-account and grant it the required permissions with the following script.

  #!/usr/bin/env bash
  
  # @note gcloud_sdk_version '487.0.0'
  
  PROJECT_ID=YOUR-PROJECT-ID # TODO replace with your project id
  SERVICE_ACCOUNT_NAME=lightlike-cli
  SERVICE_ACCOUNT_EMAIL="$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"
  # TODO store somewhere safe, or immediately remove from the machine after starting the cli.
  KEY_FILE=~/lightlike-credentials.json
  
  # Create a new service account.
  gcloud iam service-accounts create \
      "$SERVICE_ACCOUNT_NAME" \
      --description="https://github.com/ayvi-0001/lightlike-cli" \
      --display-name="lightlike-cli"
  
  # Create a new key.
  gcloud iam service-accounts keys create "$KEY_FILE" --iam-account="$SERVICE_ACCOUNT_EMAIL"
  
  # Add the required permissions.
  gcloud projects add-iam-policy-binding "$PROJECT_ID" \
      --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
      --role=roles/bigquery.user \
      --role=roles/bigquery.metadataViewer \
      --condition=None

---

Issues

This tool is still not 100% complete. It's recommended to keep frequent backups of your time entries. Please feel free to open an issue if you encounter bugs. If any uncaught exceptions raise, a traceback will save in the app directory and you'll see a message similar to the one below:

If there is any loss of data without having created a recent snapshot, and you are within the fail-safe period of the last 7 days, there are methods to recover it.

If the table has not been dropped, you can query historical data by using the FOR SYSTEM_TIME AS OF clause.

SELECT
  *
FROM
  `lightlike_cli.timesheet`
FOR SYSTEM_TIME AS OF
  CURRENT_TIMESTAMP - INTERVAL 12 HOUR;

If the table has been dropped, you can recover it using the bq gcloud component. Use the cp command, with the unix milliseconds of the snapshot time appended to the base table name with the @ symbol.

bq cp lightlike_cli.timesheet@1723306791 lightlike_cli.timesheet

If you have gcloud installed but you run into the error bq: command not found, try running gcloud components install bq.