tog

tog is a fast CLI for Toggl Track — start timers, browse projects, list tasks, and pull time reports directly from your terminal. Built for developers who prefer the keyboard over the web UI.

Installation

Native binary (recommended)

curl -fsSL https://raw.githubusercontent.com/toddhainsworth/tog/main/scripts/install.sh | sh

This downloads the latest release for your OS and architecture, verifies the SHA256 checksum, and installs the binary to /usr/local/bin (or ~/.local/bin if that isn't writable). Override the destination with INSTALL_DIR:

INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/toddhainsworth/tog/main/scripts/install.sh | sh

Alternatively, download a binary directly from GitHub Releases or build from source:

go install github.com/toddhainsworth/tog/cmd/tog@latest

Container install (for locked-down workstations)

If Gatekeeper or MDM policy blocks the downloaded binary but Docker is available, install the wrapper script instead — it's a plain shell script and not subject to Gatekeeper:

DISCLAIMER: Only do this with express permission from your sysadmin team!

mkdir -p ~/.local/bin
curl -fsSL https://github.com/toddhainsworth/tog/releases/latest/download/tog-docker.sh \
  -o ~/.local/bin/tog && chmod +x ~/.local/bin/tog

To update the wrapper, re-run the same command. Ensure ~/.local/bin is on your PATH (on a default macOS shell setup you may need to add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc).

The wrapper mounts your config, cache, and current git repo into the container, so the command surface, .tog.yml discovery, and TOGGL_API_TOKEN env var all work identically to a native install. See docs/docker.md for the full reference.

Configuration

tog needs a Toggl API token. Get yours at https://track.toggl.com/profile.

Option 1 — config file:

# ~/.config/tog/config.yml
token: your_token_here
default_workspace_id: 12345

Option 2 — environment variable (recommended for CI):

export TOGGL_API_TOKEN=your_token_here

The environment variable takes precedence over the config file.

For a guided setup, run tog config init — it walks you through token entry (hidden input, validated against /me) and picks a default workspace. If you use a secrets manager (1Password, Bitwarden, pass), see docs/secrets.md for the op run pattern.

Project config (.tog.yml)

Place a .tog.yml file in your project directory (or any parent up to the git root) to set per-project defaults:

# .tog.yml
project: 12345678
workspace: 87654321

Both fields are optional and accept numeric IDs only. When present, timer start and tasks list use these as defaults — explicit --project and --workspace flags always override them.

To find the right IDs, run tog projects list which prints each project's ID alongside its name.

Command Reference

Command	Description
whoami	Print the authenticated user's name
timer	Start, stop, and list time entries
projects	Browse workspace projects
tasks	List tasks within a project
report	Daily and weekly time summaries
config	Inspect and modify tog configuration (init, set, get, path)
update	Update tog to the latest release

Updating

Native binary installs can update in place:

tog update

This checks GitHub for a newer release, downloads the archive for your platform, verifies the SHA-256 checksum, and atomically replaces the running binary. If you are already on the latest version, it prints "already at latest (v1.2.3)" and exits.

If you are running tog directly inside a Docker container, update the image instead:

docker pull ghcr.io/toddhainsworth/tog:latest

For native installs, the install script is for first-time use only. To force a reinstall or change the install path, re-run the install script directly.

Development

go test ./...       # run tests
go build ./...      # build
go vet ./...        # vet

License

MIT © Todd Hainsworth — see LICENSE.