crowdtime-cli 0.5.0

AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest

CrowdTime CLI

AI-powered time tracking from your terminal. A modern, developer-friendly alternative to Harvest.

Track time, manage projects, log expenses, generate reports, submit timesheets, create invoices, and get AI-powered insights — all without leaving your terminal.

Features

• Fast time tracking — Start/stop timers or log entries directly with natural duration formats (2h30m, 1:45, 0.5d)
• AI-powered — Natural language time entry, smart suggestions based on your patterns, and automatic standup/slack summaries
• Timesheets — Submit, approve, and reject timesheets with team overview for managers
• Expense tracking — Log expenses with categories, vendors, receipts, and billable flags; include on invoices
• Invoicing — Create invoices from tracked time and expenses, send PDFs, record payments, manage recurring templates and retainers
• Rich terminal UI — Beautiful tables, dashboards, and reports powered by Rich
• Multi-org support — Switch between organizations seamlessly
• Secure by default — API tokens stored in your OS keychain, never in plain text
• Flexible reporting — Daily, weekly, monthly reports in table, JSON, CSV, or Markdown formats
• Favorites & templates — Save common entries for one-command reuse
• LLM skill integration — Ships with skills for Claude Code, Codex, Gemini, and Cursor

Installation

pip install crowdtime-cli

Requires Python 3.11+

Quick Start

# Authenticate
ct config set server.url https://api.crowdtime.lat
ct auth login

# Switch to your organization
ct org switch my-org

# Start tracking
ct timer start "Building REST API" -p backend -t "Development"
ct timer stop

# Or log time directly
ct log -p backend -t "Code Review" 2h "Reviewed auth module PR"

# Check your day
ct status

# Weekly report
ct report --week

Command Overview

Time Tracking

Command	Alias	Description
ct status	ct s	Dashboard: running timer, today's entries, weekly total
ct timer start	ct ts	Start a timer with project and task
ct timer stop	ct tx	Stop the running timer and save the entry
ct timer switch	—	Atomically stop current timer and start a new one
ct timer discard	—	Discard running timer without saving
ct log <duration> <desc>	ct l	Log a time entry directly
ct log list	ct ll	List time entries (today, --week, --month)
ct log edit <id>	—	Edit an existing entry
ct log delete <id>	—	Delete a time entry

Projects & Organization

Command	Alias	Description
ct projects list	ct p	List projects
ct projects create	—	Create a new project (auto-creates client if needed)
ct projects switch	—	Set a default project for new entries
ct clients list	—	List clients
ct clients create	—	Create a new client
ct clients contacts <id>	—	List contacts for a client
ct clients add-contact <id>	—	Add a contact to a client
ct tasks list	—	List tasks (optionally filtered by project)
ct tasks create	—	Create a task and assign to a project
ct favorites list	—	List saved entry templates
ct favorites start <id>	—	Start a timer from a saved template
ct org list	—	List your organizations
ct org switch <slug>	—	Switch active organization
ct org members	—	List organization members
ct org invite <email>	—	Invite a new member (roles: viewer, member, project_manager, manager, admin)
ct org invitations	—	List pending invitations
ct org resend-invite <id>	—	Resend a pending invitation email

Reporting & AI

Command	Alias	Description
ct report	ct r	Generate reports (--week, --month, --group-by, --format)
ct report projects	—	Project breakdown report
ct report team	—	Team utilization report
ct ai suggest	—	Get AI suggestions based on your work patterns
ct ai summarize	—	AI-generated summaries (--for standup, --for slack, --copy)

Timesheets

Command	Description
ct timesheet list	List your timesheets (all statuses)
ct timesheet submit --from DATE --to DATE	Submit a timesheet for approval
ct timesheet approve <id>	Approve a submitted timesheet (manager+)
ct timesheet reject <id> --notes "..."	Reject with feedback (manager+)
ct timesheet team	Team overview: hours, entries, status per member (manager+)
ct timesheet viewable-users	List members you can view timesheets for

Expenses

Command	Description
ct expense list	List expenses (filter by --project, --category, --from/--to)
ct expense create	Create an expense (amount, vendor, date, category, project)
ct expense edit <id>	Edit an existing expense
ct expense delete <id>	Delete an expense
ct expense categories	List expense categories
ct expense add-category	Create a new expense category

Invoicing

Command	Description
ct invoice list	List invoices (filter by --status, --client, --type)
ct invoice show <id>	Detailed view with line items, totals, payments
ct invoice create --client <id> --from DATE --to DATE	Create invoice from tracked time
ct invoice create-blank --client <id> --issue-date DATE	Create empty invoice for manual items
ct invoice add-item <id> --desc "..." --qty N --rate N	Add a line item to a draft
ct invoice send <id>	Send invoice to client via email with PDF
ct invoice pay <id> --amount N	Record a payment
ct invoice void <id> --reason "..."	Void an invoice
ct invoice pdf <id>	Download invoice as PDF
ct invoice duplicate <id>	Duplicate as a new draft
ct invoice recurring list	List recurring invoice templates
ct invoice retainer list	List retainer agreements

Configuration & Skills

Command	Description
ct config set KEY VALUE	Set a config value (dot notation)
ct config get KEY	Get a config value
ct config list	Show all configuration
ct config edit	Open config in your editor
ct skill install	Install LLM skill (see below)
ct skill status	Show skill installation status
ct skill uninstall	Remove the skill

Duration Formats

2h | 2h30m | 2:30 | 150m | 0.25d (1 day = 8h) | 1.5 (hours)

Date Formats

today | yesterday | monday..sunday | last friday | 2026-03-10 | 3/10

LLM Skill Installation

CrowdTime ships with built-in skills for AI coding assistants. Once installed, your LLM can track time, manage timesheets, and create invoices on your behalf.

Supported tools

Tool	Skill activation
Claude Code	Auto-activates when time tracking is mentioned, or use /crowdtime
Codex	Auto-activates, or use $crowdtime
Gemini	Auto-activates when time tracking is mentioned
Cursor	Auto-activates in agent mode

Install the skill

# Auto-detect your tool and install to the current project
ct skill install

# Install globally (user-wide, works across all projects)
ct skill install --global

# Install for a specific tool
ct skill install --tool claude --global
ct skill install --tool codex
ct skill install --tool gemini --global
ct skill install --tool cursor

# Install for all detected tools at once
ct skill install --all --global

Manage skills

# Check installation status across all tools
ct skill status

# Update to latest version (re-run install)
ct skill install --global

# Uninstall
ct skill uninstall --global
ct skill uninstall --tool claude
ct skill uninstall --all

What the skill enables

Once installed, your LLM coding assistant can:

• Track time — "log 2 hours on the backend project for API work"
• Manage timers — "start a timer for code review on project alpha"
• Submit timesheets — "submit my timesheet for this week"
• Review team — "show me the team's timesheet status for this week"
• Create invoices — "create an invoice for Acme Corp for March"
• Send invoices — "send the draft invoice to the client"
• Generate reports — "show me this month's hours by project"

The skill teaches the LLM to construct proper CLI commands — it never uses magic routing or guesses parameters.

Configuration

ct config set server.url https://api.crowdtime.lat   # API server
ct config set defaults.project my-project             # Default project
ct config set defaults.daily_target 7h                # Daily hour target
ct config list                                        # Show all settings

Config is stored at ~/.crowdtime/config.toml.

Authentication

CrowdTime supports multiple auth methods:

ct auth login                    # Browser-based Google OAuth (default)
ct auth login --token <token>    # API token (for CI/scripts)
ct auth login --no-browser       # Token prompt (headless environments)

API tokens are stored securely in your OS keychain via keyring.

Requirements

• Python 3.11+
• A CrowdTime account at crowdtime.lat

Support

For issues and feature requests, contact [e-mail].

License

Proprietary. See LICENSE for details.