Metadata-Version: 2.4
Name: crowdtime-cli
Version: 0.11.0
Summary: AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest
Project-URL: Homepage, https://crowdtime.lat
Project-URL: Documentation, https://crowdtime.lat/docs
Project-URL: Support, https://crowdtime.lat/support
Author-email: IT Crowd <dev@itcrowdarg.com>
License: Proprietary
License-File: LICENSE
Keywords: ai,cli,harvest-alternative,productivity,time-tracking
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: humanize>=4.0
Requires-Dist: keyring>=25.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.9
Requires-Dist: rich>=13.0
Requires-Dist: tomlkit>=0.12.0
Requires-Dist: typer[all]>=0.12.0
Description-Content-Type: text/markdown

# 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

```bash
pip install crowdtime-cli
```

Requires Python 3.11+

## Quick Start

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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:

```bash
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](https://pypi.org/project/keyring/).

## Requirements

- Python 3.11+
- A CrowdTime account at [crowdtime.lat](https://crowdtime.lat)

## Support

For issues and feature requests, contact [dev@itcrowdarg.com](mailto:dev@itcrowdarg.com).

## License

Proprietary. See [LICENSE](LICENSE) for details.
