⏱️ Toggl Track CLI Helper

A powerful command-line interface for Toggl Track time tracking. Streamline your time tracking workflow with easy-to-use commands for starting, stopping, and managing time entries.

✨ Features

• ⚡ Quick time tracking with simple start/stop commands
• 📋 Project management with easy project ID lookup
• 🏷️ Tag support for organizing time entries
• 🏢 Workspace integration with multi-workspace support
• 🎨 Pretty output with JSON formatting (jq/python3)
• 🔧 Flexible configuration with multiple config file locations
• ⚡ Zsh completion with smart tab completion
• 🔒 Secure authentication via API tokens

🚦 Quick Start

One-line Installation

curl -fsSL https://raw.githubusercontent.com/jeromecoloma/toggl-track/main/install.sh | bash

Manual Installation

1. Download and install:

   git clone https://github.com/jeromecoloma/toggl-track.git
   cd toggl-track
   chmod +x install.sh
   ./install.sh

2. Restart your shell or run:

   source ~/.zshrc

3. Initialize configuration (optional):

   toggl-track init

Update

To update to the latest version:

curl -fsSL https://raw.githubusercontent.com/jeromecoloma/toggl-track/main/install.sh | bash -s -- --update

Or use the built-in update command:

toggl-track --update

Uninstallation

To remove toggl-track completely:

curl -fsSL https://raw.githubusercontent.com/jeromecoloma/toggl-track/main/install.sh | bash -s -- --uninstall

Or locally:

./install.sh --uninstall

📖 Usage

Basic Commands

# Initialize configuration interactively
toggl-track init

# Start a new time entry
toggl-track start "Working on project"

# Start with specific project and tags
toggl-track start "Bug fixes" 12345678 --tags "development,bugfix"

# Stop current time entry
toggl-track stop

# Check current status
toggl-track status

# List workspaces
toggl-track list-workspaces

# List all projects
toggl-track list-projects

# List projects in specific workspace
toggl-track list-projects-ws 987654

# Find project ID by name
toggl-track proj-id "My Project"

Advanced Usage

# Start entry with default project from config
toggl-track start "Daily standup"

# Use raw JSON output (no formatting)
TOGGL_FORMAT=raw toggl-track status

# Debug mode (shows loaded config file)
TOGGL_DEBUG=1 toggl-track start "Debug session"

⚙️ Configuration

Quick Setup with Init Command

The easiest way to set up configuration:

toggl-track init

This interactive command will:

• Guide you through getting your API token
• Help you find your Workspace ID
• Optionally set up default project, tags, and description
• Create a properly formatted .toggltrackrc file

Configuration File Locations

Toggl looks for configuration files in these locations (first found wins):

1. ./.toggltrackrc (project-specific)
2. ~/.toggltrackrc (user-specific)
3. ~/.config/toggl-track/.toggltrackrc (XDG config)

Sample Configuration (~/.toggltrackrc)

# API Authentication (required)
TOGGL_API_TOKEN="your_toggl_api_token_here"

# Default workspace and project (optional)
TOGGL_WORKSPACE_ID="987654321"
TOGGL_PROJECT_ID="123456789"

# Default settings (optional)
TOGGL_DESC="Default description"
TOGGL_TAGS="work,development"

# Output format (optional)
TOGGL_FORMAT="pretty"  # or "raw"
TOGGL_DEBUG="0"        # or "1" for debug info

Getting Your API Token

1. Go to Toggl Track Profile
2. Scroll to "API Token" section
3. Copy your API token
4. Add it to your config file

Getting Workspace and Project IDs

# List your workspaces
toggl-track list-workspaces

# List all your projects
toggl-track list-projects

# List projects in specific workspace
toggl-track list-projects-ws 987654321

# Find project ID by name (fuzzy search)
toggl-track proj-id "My Project Name"

🎯 Tab Completion

Toggl includes intelligent Zsh completion that provides:

• Command completion: toggl-track st<TAB> → start, status, stop
• Flag completion: toggl-track start --<TAB> → shows available flags
• Context-aware options: Different commands show relevant flags

🔧 Commands Reference

Command	Description	Arguments
init	Interactive configuration setup	None
start	Start new time entry	[description] [project_id] [--tags "tag1,tag2"]
stop	Stop current time entry	None
status	Show current time entry	None
list-workspaces	List all workspaces	None
list-projects	List all projects	None
list-projects-ws	List projects in workspace	[workspace_id]
proj-id	Find project ID by name	<name_substring>

📝 Environment Variables

Variable	Description	Default
TOGGL_FORMAT	Output format (pretty|raw)	pretty
TOGGL_DEBUG	Debug mode (0|1)	0

🛠️ Development

Local Development Setup

git clone https://github.com/jeromecoloma/toggl-track.git
cd toggl-track

File Structure

toggl-track/
├── toggl-track          # Main script
├── completions/         # Zsh completion
│   └── _toggl_track
├── install.sh          # Installation script
├── README.md           # This file
├── LICENSE             # MIT License
└── examples/           # Configuration examples
    └── .toggltrackrc.example

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📝 Examples

Complete Workflow

# 1. Setup configuration interactively
toggl-track init

# 2. Find your project (if not set in init)
toggl-track list-projects

# 3. Start tracking
toggl-track start "Working on new feature" 987654321 --tags "development,feature"

# 4. Check status
toggl-track status

# 5. Stop when done
toggl-track stop

Alternative Manual Setup

# 1. Configure API token manually
echo 'TOGGL_API_TOKEN="your_token_here"' > ~/.toggltrackrc
echo 'TOGGL_WORKSPACE_ID="123456789"' >> ~/.toggltrackrc

# 2. Continue with workflow above

Daily Usage

# Morning standup
toggl-track start "Daily standup"

# Switch to development work
toggl-track stop
toggl-track start "Feature development" --tags "development,sprint-1"

# Lunch break (stop tracking)
toggl-track stop

# Afternoon work
toggl-track start "Code review" --tags "review"

🆘 Troubleshooting

Common Issues

Command not found:

# Check if ~/bin is in PATH
echo $PATH

# Add to ~/.zshrc if missing
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission denied:

# Make script executable
chmod +x ~/bin/toggl-track

API authentication failed:

# Check your API token
toggl-track list-workspaces

# Verify config file
cat ~/.toggltrackrc

Tab completion not working:

# Rebuild completion cache
rm ~/.zcompdump*
exec zsh

No config file found:

# Use interactive setup (recommended)
toggl-track init

# Or create config file manually
echo 'TOGGL_API_TOKEN="your_token"' > ~/.toggltrackrc
echo 'TOGGL_WORKSPACE_ID="your_workspace_id"' >> ~/.toggltrackrc

Configuration errors:

• The tool now shows helpful error messages with clear instructions
• Missing variables are highlighted with suggestions
• Configuration errors won't crash the script

🔒 Security Best Practices

1. Keep API tokens secure - don't commit them to version control
2. Use environment-specific configs for different projects
3. Regularly rotate API tokens if compromised
4. Set proper file permissions on config files (600)

📄 License

MIT License - see LICENSE file for details.

---

Found this useful? ⭐ Star the repo and share with your team!