crowdtime-cli 0.1.0__py3-none-any.whl

crowdtime_cli/skills/crowdtime/references/commands.md

@@ -0,0 +1,659 @@
+# CrowdTime CLI — Complete Command Reference
+
+Every command, subcommand, argument, flag, and option in the CrowdTime CLI.
+
+## Table of Contents
+
+- [Global Behavior](#global-behavior)
+- [ct (bare / status)](#ct-bare--status)
+- [ct auth](#ct-auth)
+- [ct timer](#ct-timer)
+- [ct log](#ct-log)
+- [ct clients](#ct-clients)
+- [ct projects](#ct-projects)
+- [ct tasks](#ct-tasks)
+- [ct report](#ct-report)
+- [ct ai](#ct-ai)
+- [ct favorites](#ct-favorites)
+- [ct org](#ct-org)
+- [ct config](#ct-config)
+- [Short Aliases](#short-aliases)
+
+---
+
+## Global Behavior
+
+- Entry points: `crowdtime` and `ct` (identical)
+- Config file: `~/.crowdtime/config.toml`
+- Token storage: OS keychain (via `keyring`), fallback to `~/.crowdtime/credentials`
+- All org-scoped commands require: authenticated user + active organization
+- `--json` flag on most commands outputs machine-readable JSON
+
+### Magic Routing
+
+Any unrecognized first argument routes to AI parsing:
+```bash
+ct "2h on project alpha code review"   # → ct ai parse "..."
+```
+
+---
+
+## ct (bare / status)
+
+Shows full status dashboard.
+
+```
+ct
+ct status [--json]
+ct s [--json]           # alias
+```
+
+**Output includes:**
+- Authenticated user and current organization
+- Running timer (if any) with elapsed HH:MM:SS
+- Today's entries with progress bar toward daily target
+- This week's breakdown with daily hour bars
+
+**Endpoints called:**
+- `GET /api/v1/auth/me/`
+- `GET /time/running/`
+- `GET /time/daily/{today}/`
+- `GET /time/weekly/{monday}/`
+
+---
+
+## ct auth
+
+### ct auth login
+
+```
+ct auth login [--token/-t TOKEN] [--no-browser] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--token`, `-t` | string | API token (skips browser login) |
+| `--no-browser` | flag | Prompt for token instead of opening browser |
+| `--json` | flag | JSON output |
+
+- Default (no flags): opens browser for Google OAuth login
+- `--token`: provide an API token directly
+- `--no-browser`: prompts for token interactively (useful for headless environments)
+- Stores token in OS keychain with file fallback
+- Validates by calling `GET /api/v1/auth/me/`
+
+### ct auth logout
+
+```
+ct auth logout
+```
+
+Removes stored credentials from keychain and file.
+
+### ct auth whoami
+
+```
+ct auth whoami [--json]
+```
+
+Shows: name, email, timezone, current organization.
+
+---
+
+## ct timer
+
+### ct timer start
+
+```
+ct timer start [DESCRIPTION] [options]
+```
+
+| Argument/Option | Type | Description |
+|-----------------|------|-------------|
+| `DESCRIPTION` | string (optional) | What you're working on |
+| `--project`, `-p` | string | Project slug or UUID |
+| `--task`, `-t` | string | Task name or UUID (auto-creates and assigns if needed) |
+| `--billable`, `-b` | flag | Mark as billable |
+| `--no-billable`, `-B` | flag | Mark as non-billable |
+| `--json` | flag | JSON output |
+
+- Fails if a timer is already running (use `switch` instead)
+- Uses default project from config if `--project` not specified
+- Endpoint: `POST /time/start/`
+
+### ct timer stop
+
+```
+ct timer stop [--note/-n NOTE] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--note`, `-n` | string | Add a note to the completed entry |
+| `--json` | flag | JSON output |
+
+- Returns 404 if no timer running
+- Endpoint: `POST /time/stop/`
+
+### ct timer status
+
+```
+ct timer status [--json]
+```
+
+Shows running timer with elapsed HH:MM:SS, description, project, task, billable status.
+Endpoint: `GET /time/running/`
+
+### ct timer switch
+
+```
+ct timer switch [DESCRIPTION] [options]
+```
+
+Same arguments and options as `timer start`. Atomically stops the current timer and starts a new one.
+
+### ct timer discard
+
+```
+ct timer discard [--force/-f]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--force`, `-f` | flag | Skip confirmation prompt |
+
+Discards the running timer without saving any time entry.
+
+---
+
+## ct log
+
+**Bare `ct log` (no arguments)** lists today's entries (same as `ct log list`).
+
+`ct log` with options/args auto-routes to `ct log create` — all three forms below are equivalent:
+- `ct log -p proj 2h "work"`
+- `ct log create -p proj 2h "work"`
+- `ct l -p proj 2h "work"`
+
+### ct log create
+
+```
+ct log [create] [OPTIONS] DURATION [DESCRIPTION]
+```
+
+**IMPORTANT: Options MUST come BEFORE positional arguments (duration, description).** This is a Typer/Click constraint.
+
+| Argument/Option | Type | Description |
+|-----------------|------|-------------|
+| `DURATION` | string (required) | Time spent: `2h`, `2h30m`, `2:30`, `150m`, `0.25d`, or number |
+| `DESCRIPTION` | string (optional) | What you worked on |
+| `--project`, `-p` | string | Project slug or UUID |
+| `--task`, `-t` | string | Task name or UUID (auto-creates and assigns if needed) |
+| `--date`, `-d` | string | Date (default: today) |
+| `--billable`, `-b` | flag | Billable |
+| `--no-billable`, `-B` | flag | Non-billable |
+| `--json` | flag | JSON output |
+
+**Usage examples:**
+```bash
+ct log -p crowdtime-dev 2h "code review"
+ct log -p crowdtime-dev -t "Research" -d yesterday 2h30m "meeting"
+
+# Short alias (ct l):
+ct l -p crowdtime-dev 2h "code review"
+ct l -p crowdtime-dev -t "Design" 1:30 "wireframes"
+```
+
+**Duration formats:**
+| Format | Example | Result |
+|--------|---------|--------|
+| Hours | `2h` | 2.0 hours |
+| Hours + minutes | `2h30m` | 2.5 hours |
+| HH:MM | `2:30` | 2.5 hours |
+| Minutes | `150m` | 2.5 hours |
+| Days | `0.25d` | 2.0 hours (1d = 8h) |
+| Decimal | `2.5` | 2.5 hours |
+
+**Date formats:**
+| Format | Example |
+|--------|---------|
+| Keywords | `today`, `yesterday` |
+| Day names | `monday`, `tue`, `fri` |
+| Last + day | `last friday` |
+| ISO | `2026-03-10` |
+| US short | `3/10`, `03/10/2026` |
+
+Endpoint: `POST /time/`
+
+### ct log edit
+
+```
+ct log edit ENTRY_ID [options]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--duration` | string | New duration |
+| `--description` | string | New description |
+| `--project`, `-p` | string | New project |
+| `--task`, `-t` | string | New task (name or UUID) |
+| `--date`, `-d` | string | New date |
+| `--billable`, `-b` | flag | Set billable |
+| `--no-billable`, `-B` | flag | Set non-billable |
+| `--json` | flag | JSON output |
+
+Only provided fields are updated. Endpoint: `PATCH /time/{id}/`
+
+### ct log delete
+
+```
+ct log delete ENTRY_ID [--force/-f]
+```
+
+Requires confirmation unless `--force`. Endpoint: `DELETE /time/{id}/`
+
+### ct log list
+
+```
+ct log list [options]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--date`, `-d` | string | Specific date |
+| `--week`, `-w` | flag | This week |
+| `--month`, `-m` | flag | This month |
+| `--from` | string | Start date for range |
+| `--to` | string | End date for range |
+| `--project`, `-p` | string | Filter by project |
+| `--format` | string | Output: `table`, `json`, `csv` |
+| `--json` | flag | JSON output |
+
+Endpoint: `GET /time/`
+
+---
+
+## ct clients
+
+### ct clients list
+
+```
+ct clients list [--archived/-a] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--archived`, `-a` | flag | Include archived clients |
+| `--json` | flag | JSON output |
+
+Shows: ID, Name, Contact, Projects count, Status.
+Endpoint: `GET /clients/`
+
+### ct clients show
+
+```
+ct clients show CLIENT_ID [--json]
+```
+
+Shows: ID, name, currency, contact info, status.
+Endpoint: `GET /clients/{id}/`
+
+### ct clients create
+
+```
+ct clients create NAME [options]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--currency` | string | Currency code (e.g. USD) |
+| `--contact` | string | Contact person name |
+| `--email` | string | Contact email |
+| `--json` | flag | JSON output |
+
+Endpoint: `POST /clients/`
+
+### ct clients archive
+
+```
+ct clients archive CLIENT_ID [--force/-f]
+```
+
+Soft-archives the client. Requires confirmation unless `--force`.
+Endpoint: `DELETE /clients/{id}/`
+
+---
+
+## ct projects
+
+### ct projects list
+
+```
+ct projects list [--archived/-a] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--archived`, `-a` | flag | Include archived projects |
+| `--json` | flag | JSON output |
+
+Shows: ID, Name, Code, Client, Status, Billable. Marks default project.
+Endpoint: `GET /projects/`
+
+### ct projects show
+
+```
+ct projects show PROJECT_ID [--json]
+```
+
+Shows: ID, code, client, status, billable, budget, description.
+Endpoint: `GET /projects/{id}/`
+
+### ct projects create
+
+```
+ct projects create NAME [options]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--client`, `-c` | string | Client name (auto-creates if not found) |
+| `--billable`, `-b` | flag | Billable (default: true) |
+| `--no-billable`, `-B` | flag | Non-billable |
+| `--color` | string | Hex color code |
+| `--budget` | float | Budget in hours |
+| `--code` | string | Short project code |
+| `--json` | flag | JSON output |
+
+Endpoint: `POST /projects/`
+
+### ct projects archive
+
+```
+ct projects archive PROJECT_ID [--force/-f]
+```
+
+Requires confirmation unless `--force`. Endpoint: `PATCH /projects/{id}/`
+
+### ct projects switch
+
+```
+ct projects switch SLUG
+```
+
+Sets project as default for new entries. Saves to config `defaults.project`.
+
+---
+
+## ct tasks
+
+### ct tasks list
+
+```
+ct tasks list [--project/-p PROJECT] [--json]
+```
+
+Shows: ID, Name, Project, Billable. Endpoint: `GET /tasks/`
+
+### ct tasks create
+
+```
+ct tasks create NAME [--project/-p PROJECT] [--billable/-b] [--no-billable/-B] [--json]
+```
+
+Creates an organization-level task. If `--project` is specified, also assigns the task to that project (via ProjectTask).
+Endpoint: `POST /tasks/` + `POST /projects/{id}/tasks/`
+
+---
+
+## ct report
+
+### ct report (main)
+
+```
+ct report [period options] [filter options] [output options]
+```
+
+**Period options** (default: this week):
+
+| Option | Description |
+|--------|-------------|
+| `--today` | Today only |
+| `--yesterday` | Yesterday |
+| `--week`, `-w` | This week |
+| `--last-week` | Last week |
+| `--month`, `-m` | This month |
+| `--from` | Start date (with optional `--to`) |
+| `--to` | End date |
+
+**Filter options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--project`, `-p` | string | Filter by project |
+
+**Output options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--group-by`, `-g` | string | `project` (default), `task`, `day`, `client` |
+| `--format`, `-f` | string | `table` (default), `json`, `csv`, `markdown` |
+
+Endpoint: `GET /reports/time-detail/` or `GET /reports/project-summary/`
+
+### ct report projects
+
+```
+ct report projects [--week/-w] [--month/-m] [--json]
+```
+
+Project breakdown with hours, billable, budget info. Default: this month.
+
+### ct report team
+
+```
+ct report team [--week/-w] [--month/-m] [--member MEMBER] [--json]
+```
+
+Team utilization: Member, Hours, Billable, Utilization %. Endpoint: `GET /reports/team-utilization/`
+
+---
+
+## ct ai
+
+### ct ai parse
+
+```
+ct ai parse TEXT [--dry-run] [--yes/-y] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `TEXT` | string (required) | Natural language time entry |
+| `--dry-run` | flag | Preview without creating |
+| `--yes`, `-y` | flag | Skip confirmation |
+| `--json` | flag | JSON output |
+
+Shows parsed: description, project, task, duration, date, billable, confidence, ambiguities.
+Endpoints: `POST /ai/parse/` then `POST /ai/parse/confirm/`
+
+### ct ai suggest
+
+```
+ct ai suggest [--date/-d DATE] [--json]
+```
+
+AI-powered suggestions based on work patterns. Interactive: select a suggestion to start a timer.
+Endpoint: `GET /ai/suggestions/`
+
+### ct ai summarize
+
+```
+ct ai summarize [period] [--for FORMAT] [--copy/-c] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--today` | flag | Today |
+| `--week`, `-w` | flag | This week (default) |
+| `--month`, `-m` | flag | This month |
+| `--for` | string | `report` (default), `standup`, `slack` |
+| `--copy`, `-c` | flag | Copy to clipboard |
+| `--json` | flag | JSON output |
+
+Generates headline, total hours, project breakdown, insights.
+Endpoint: `GET /ai/summary/weekly/`
+
+---
+
+## ct favorites
+
+### ct favorites list
+
+```
+ct favorites list [--json]
+```
+
+Shows: ID, Project, Task, Description, Use count. Endpoint: `GET /favorites/`
+
+### ct favorites create
+
+```
+ct favorites create [DESCRIPTION] [--project/-p] [--task/-t] [--notes/-n] [--billable/-b] [--no-billable/-B] [--json]
+```
+
+Creates a reusable entry template. Endpoint: `POST /favorites/`
+
+### ct favorites delete
+
+```
+ct favorites delete FAVORITE_ID [--force/-f]
+```
+
+Endpoint: `DELETE /favorites/{id}/`
+
+### ct favorites start
+
+```
+ct favorites start FAVORITE_ID [--json]
+```
+
+Starts a timer from a saved template. Endpoint: `POST /favorites/{id}/start/`
+
+---
+
+## ct org
+
+### ct org list
+
+```
+ct org list [--json]
+```
+
+Lists organizations you belong to. Marks current with `*`. Non-org-scoped.
+Endpoint: `GET /api/v1/organizations/`
+
+### ct org switch
+
+```
+ct org switch SLUG
+```
+
+Switches active organization. Saves to config `defaults.organization`.
+
+### ct org members
+
+```
+ct org members [--json]
+```
+
+Shows: Name, Email, Role, Status. Endpoint: `GET /members/`
+
+### ct org invite
+
+```
+ct org invite EMAIL [--role/-r ROLE] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--role`, `-r` | string | `admin`, `manager`, `member` (default) |
+
+Endpoint: `POST /members/invite/`
+
+---
+
+## ct config
+
+### ct config set
+
+```
+ct config set KEY VALUE
+```
+
+Uses dot notation. Examples:
+- `ct config set server.url https://api.crowdtime.io`
+- `ct config set defaults.project myproject`
+- `ct config set defaults.daily_target 7h`
+- `ct config set display.compact true`
+
+Auto-converts boolean strings.
+
+### ct config get
+
+```
+ct config get KEY
+```
+
+### ct config list
+
+```
+ct config list [--json]
+```
+
+Shows all config with file path.
+
+### ct config edit
+
+```
+ct config edit
+```
+
+Opens in `$EDITOR`, `$VISUAL`, or `nano`.
+
+### Config Structure
+
+```toml
+[server]
+url = "https://api.crowdtime.lat"
+
+[defaults]
+organization = ""
+project = ""
+daily_target = "8h"
+weekly_target = "40h"
+date_format = "%Y-%m-%d"
+time_format = "24h"
+
+[display]
+theme = "auto"
+color = true
+compact = false
+```
+
+---
+
+## Short Aliases
+
+| Alias | Expands To |
+|-------|-----------|
+| `ct` | `ct status` |
+| `ct s` | `ct status` |
+| `ct t` | `ct timer status` |
+| `ct ts` | `ct timer start` |
+| `ct tx` | `ct timer stop` |
+| `ct l` | `ct log` (create) |
+| `ct ll` | `ct log list` |
+| `ct p` | `ct projects list` |
+| `ct r` | `ct report` |
+| `ct "text"` | `ct ai parse "text"` |