crowdtime-cli 0.22.0__tar.gz → 0.23.0__tar.gz

{crowdtime_cli-0.22.0 → crowdtime_cli-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.22.0
+Version: 0.23.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

{crowdtime_cli-0.22.0 → crowdtime_cli-0.23.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.22.0"
+version = "0.23.0"
 description = "AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest"
 readme = "README.md"
 license = {text = "Proprietary"}

{crowdtime_cli-0.22.0 → crowdtime_cli-0.23.0}/src/crowdtime_cli/__init__.py

@@ -1,3 +1,3 @@
 """CrowdTime CLI - AI-powered time tracking from the command line."""
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"

{crowdtime_cli-0.22.0 → crowdtime_cli-0.23.0}/src/crowdtime_cli/commands/invoice_cmd.py

@@ -572,6 +572,41 @@ def show_invoice(
         raise typer.Exit(1)
 
 
+# How hours are shown on an invoice (CRO-94). "person" is accepted for "user".
+HOURS_DISPLAYS = {
+    "project": "project", "task": "task", "user": "user", "person": "user",
+    "date": "date", "none": "none", "detailed": "detailed",
+}
+LINE_DETAILS = ["date", "person", "project", "task", "notes"]
+GROUP_BY_HELP = (
+    "How to display hours: project, task, person (one line each, per project), "
+    "detailed (one line per time entry), date, or none (everything on one line)."
+)
+DETAILS_HELP = (
+    "What each detailed line shows (implies --group-by detailed), comma-separated "
+    "from date, person, project, task, notes. Default: person,date,notes."
+)
+
+
+def _display_payload(group_by: Optional[str], details: Optional[str]) -> dict:
+    """Validate --group-by / --details into API fields, or raise ValueError."""
+    payload: dict = {}
+    if group_by is not None:
+        resolved = HOURS_DISPLAYS.get(group_by.strip().lower())
+        if resolved is None:
+            raise ValueError(f"Invalid --group-by. Choose from: {', '.join(HOURS_DISPLAYS)}.")
+        payload["group_by"] = resolved
+    if details is not None:
+        items = [d.strip().lower() for d in details.split(",") if d.strip()]
+        bad = [d for d in items if d not in LINE_DETAILS]
+        if bad or not items:
+            raise ValueError(f"Invalid --details. Choose from: {', '.join(LINE_DETAILS)}.")
+        if payload.setdefault("group_by", "detailed") != "detailed":
+            raise ValueError("--details only applies to --group-by detailed.")
+        payload["line_details"] = items
+    return payload
+
+
 @app.command("create")
 def create_invoice(
     client_id: str = typer.Option(..., "--client", "-c", help="Client ID."),
@@ -597,9 +632,8 @@ def create_invoice(
             "its next unbilled payment; each payment is billed only once."
         ),
     ),
-    group_by: Optional[str] = typer.Option(
-        None, "--group-by", "-g", help="Group line items by: project, task, user, date, none."
-    ),
+    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help=GROUP_BY_HELP),
+    details: Optional[str] = typer.Option(None, "--details", help=DETAILS_HELP),
     tax_rate: Optional[float] = typer.Option(
         None, "--tax-rate", help="Tax rate percentage (e.g. 21 for 21%)."
     ),
@@ -634,6 +668,8 @@ def create_invoice(
     Examples:
         ct invoice create --client <id> --from 2026-03-01 --to 2026-03-31
         ct invoice create --client <id> --period last-month --group-by project
+        ct invoice create --client <id> --period last-month --group-by person
+        ct invoice create --client <id> --period last-month --group-by detailed --details date,person,notes
         ct invoice create --client <id> --period last-2-weeks --payment-terms net30
         ct invoice create --client <id> --from monday --to friday --payment-terms 15
         ct invoice create --client <id> --period last-month --due-date 2026-09-15
@@ -704,8 +740,11 @@ def create_invoice(
             format_error("--payment needs the fixed-fee project selected with --project.")
             raise typer.Exit(1)
         payload["milestone_ids"] = list(payments)
-    if group_by:
-        payload["group_by"] = group_by
+    try:
+        payload.update(_display_payload(group_by, details))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if tax_rate is not None:
         payload["tax_rate"] = str(tax_rate)
     if notes:
@@ -1384,6 +1423,9 @@ def show_recurring(
             console.print(f"  Auto-send:       {'Yes' if data.get('auto_send') else 'No'}")
             console.print(f"  Pull Entries:    {'Yes' if data.get('pull_time_entries') else 'No'}")
             console.print(f"  Group By:        {data.get('group_by', 'project')}")
+            if data.get("group_by") == "detailed":
+                shown = ", ".join(data.get("line_details") or ["person", "date", "notes"])
+                console.print(f"  Line Details:    {shown}")
 
             line_items = data.get("line_items", [])
             if line_items:
@@ -1416,7 +1458,8 @@ def create_recurring(
     payment_terms: Optional[int] = typer.Option(None, "--payment-terms", help="Payment terms in days."),
     auto_send: bool = typer.Option(False, "--auto-send", help="Automatically send generated invoices."),
     pull_entries: bool = typer.Option(True, "--pull-entries/--no-pull-entries", help="Pull time entries into invoice."),
-    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help="Group by: project, task, user, date, none."),
+    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help=GROUP_BY_HELP),
+    details: Optional[str] = typer.Option(None, "--details", help=DETAILS_HELP),
     notes: Optional[str] = typer.Option(None, "--notes", help="Invoice notes."),
     terms: Optional[str] = typer.Option(None, "--terms", help="Payment terms text."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
@@ -1442,8 +1485,11 @@ def create_recurring(
         payload["payment_terms_days"] = payment_terms
     if auto_send:
         payload["auto_send"] = True
-    if group_by:
-        payload["group_by"] = group_by
+    try:
+        payload.update(_display_payload(group_by, details))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if notes:
         payload["notes"] = notes
     if terms:
@@ -1474,7 +1520,8 @@ def update_recurring(
     active: Optional[bool] = typer.Option(None, "--active/--inactive", help="Activate or deactivate."),
     auto_send: Optional[bool] = typer.Option(None, "--auto-send/--no-auto-send", help="Auto-send invoices."),
     payment_terms: Optional[int] = typer.Option(None, "--payment-terms", help="Payment terms in days."),
-    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help="Group by: project, task, user, date, none."),
+    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help=GROUP_BY_HELP),
+    details: Optional[str] = typer.Option(None, "--details", help=DETAILS_HELP),
     notes: Optional[str] = typer.Option(None, "--notes", help="Invoice notes."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
@@ -1500,8 +1547,11 @@ def update_recurring(
         payload["auto_send"] = auto_send
     if payment_terms is not None:
         payload["payment_terms_days"] = payment_terms
-    if group_by is not None:
-        payload["group_by"] = group_by
+    try:
+        payload.update(_display_payload(group_by, details))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if notes is not None:
         payload["notes"] = notes
 

{crowdtime_cli-0.22.0 → crowdtime_cli-0.23.0}/src/crowdtime_cli/skills/crowdtime/SKILL.md

@@ -343,7 +343,8 @@ ct invoice aging                        # Overdue aging report: buckets 1-30d, 3
 ct invoice aging --client <id>          # Aging for a specific client
 ct invoice show <id>                    # Invoice details with line items
 ct invoice create --client <id> --period last-month --payment-terms net30  # From time entries
-ct invoice create --client <id> --period last-month --group-by user        # Group by team member
+ct invoice create --client <id> --period last-month --group-by person      # One line per person on each project
+ct invoice create --client <id> --period last-month --group-by detailed --details date,person,notes  # One line per entry
 ct invoice create-blank --client <id> --issue-date today --payment-terms net30  # Empty draft
 ct invoice update <id> --terms "Wire to IBAN XX" --notes "March"  # Edit draft fields
 ct invoice update <id> --subject "April Dev" --currency EUR --tax-rate <id>  # More fields
@@ -601,7 +602,7 @@ Read `references/commands.md` for the full reference of every command, subcomman
 12. **Output formats** — `ct report` supports `table`, `json`, `csv`, and `markdown` via `--format`; suggest `csv` for spreadsheet export, `markdown` for docs
 13. **Ask for details when vague** — if the user's request is ambiguous (e.g. "log 2 hours" with no description or project), ask them for the missing context rather than guessing. It's better to ask one clarifying question than to log something wrong that needs to be edited or deleted
 14. **Expenses** — when the user mentions expenses, receipts, or purchases, use the `ct expense` commands. Always suggest a category and ask if the expense is billable. If recording a billable expense for a client project, always set `--project` and `--billable` so it gets included automatically when the client is invoiced
-15. **Invoices include expenses** — when creating invoices with `ct invoice create --period`, billable expenses from the same period are automatically included as line items. Mention this to users so they know their expenses will appear on the invoice. Invoices can be grouped by `project`, `task`, `user`, `date`, or `none` via `--group-by`. Line items support discounts (`--discount-type fixed|percent|hours --discount-value N`)
+15. **Invoices include expenses** — when creating invoices with `ct invoice create --period`, billable expenses from the same period are automatically included as line items. Mention this to users so they know their expenses will appear on the invoice. Hours are shown per `--group-by`: `project`, `task` or `person` (one line each, per project, labelled with the period), `detailed` (one line per time entry; `--details` picks what each line shows from date, person, project, task, notes), `date`, or `none` (all on one line). Recurring templates take the same options. Line items support discounts (`--discount-type fixed|percent|hours --discount-value N`)
 16. **Client contacts** — use `ct clients contacts` and `ct clients add-contact` to manage multiple contacts per client. Set `--primary` for the main point of contact. Use `--receives-invoices` to flag contacts who should receive invoice emails
 17. **Permission errors are answers, not glitches** — the CLI now prints the server's reason on `403` (not your entry, already invoiced, no approval authority, read-only token, role too low) and on `400` validation errors (not assigned to the project, task not on the project). Relay the reason and the suggested alternative; do not retry the same command or look for another route to the same data. What each role can see is summarised under Team → Visibility rule and Organizations → Role hierarchy
 18. **Rate confidentiality** — rates, budgets, amounts, invoices and retainers are manager+ only (see Projects). If a member, viewer or project manager asks about rates or billed amounts, tell them it's restricted to account managers instead of trying workarounds

{crowdtime_cli-0.22.0 → crowdtime_cli-0.23.0}/src/crowdtime_cli/skills/crowdtime/references/commands.md

@@ -2029,7 +2029,7 @@ Shows invoice details including line items, payments, and totals. Endpoint: `GET
 ### ct invoice create
 
 ```
-ct invoice create --client CLIENT --from DATE --to DATE [--period PERIOD] [--group-by GROUP] [--tax-rate RATE] [--payment-terms TERMS] [--issue-date DATE] [--due-date DATE] [--notes NOTES] [--terms TEXT] [--json]
+ct invoice create --client CLIENT --from DATE --to DATE [--period PERIOD] [--group-by GROUP] [--details LIST] [--tax-rate RATE] [--payment-terms TERMS] [--issue-date DATE] [--due-date DATE] [--notes NOTES] [--terms TEXT] [--json]
 ```
 
 Creates an invoice from tracked time entries. Requires either `--from`/`--to` or `--period`.
@@ -2042,7 +2042,8 @@ Creates an invoice from tracked time entries. Requires either `--from`/`--to` or
 | `--period` | string | Preset: `last-week`, `last-2-weeks`, `last-month`, `this-month` |
 | `--project`, `-p` | string (repeatable) | Limit to specific project ID(s). **Required to bill a fixed-fee project** — those are never included in a client-wide invoice |
 | `--payment` | string (repeatable) | One-off fixed-fee payment ID(s) to bill (from `ct projects show`). Without it, each selected one-off project bills its next unbilled payment |
-| `--group-by` | string | Group line items by: `project`, `task`, `user`, `date`, `none` |
+| `--group-by` | string | How to display hours: `project`, `task`, `person` (alias `user`) — one line each, per project, e.g. "Website: Ana Pérez (Oct 1 – Oct 31, 2026)"; `detailed` — one line per time entry; `date`; `none` — all on one line. Omitted: by project, or the project's billing mode when one project is billed |
+| `--details` | string | With `detailed`: comma-separated `date`, `person`, `project`, `task`, `notes` (default `person,date,notes`), e.g. "10/23/2026 – Ana Pérez: Signup form". Implies `--group-by detailed` |
 | `--tax-rate` | float | Tax rate percentage (e.g. 21 for 21%) |
 | `--payment-terms` | string | Payment terms: `receipt` (0 days), `net7`, `net15`, `net30`, or number of days. **Omit** to resolve from the waterfall below |
 | `--issue-date` | string | Invoice date. Default: today |
@@ -2062,7 +2063,8 @@ Billable time entries and expenses from the period are automatically imported as
 ct invoice create --client <id> --period last-month --payment-terms net30
 ct invoice create --client <id> --from 2026-03-01 --to 2026-03-31
 ct invoice create --client <id> --period last-2-weeks --group-by project
-ct invoice create --client <id> --period last-month --group-by user    # One line item per team member
+ct invoice create --client <id> --period last-month --group-by person  # One line per person on each project
+ct invoice create --client <id> --period last-month --group-by detailed --details date,task,notes  # One line per entry
 ct invoice create --client <id> --period last-month                    # Uses the client's own terms
 ct invoice create --client <id> --period last-month --due-date 2026-09-15
 ct invoice create --client <id> --period last-month --project <fixed-project-id>  # Bills the next payment / one period
@@ -2203,7 +2205,8 @@ ct invoice recurring create --name NAME --client CLIENT_ID --schedule SCHEDULE -
 | `--payment-terms` | integer | Payment terms in days |
 | `--auto-send` | flag | Auto-send generated invoices |
 | `--pull-entries/--no-pull-entries` | flag | Pull time entries (default: yes) |
-| `--group-by`, `-g` | string | Group by: `project`, `task`, `user`, `date`, `none` |
+| `--group-by`, `-g` | string | How to display hours: `project`, `task`, `person`, `detailed`, `date`, `none` (see `ct invoice create`) |
+| `--details` | string | With `detailed`: what each line shows (`date,person,project,task,notes`) |
 | `--notes` | string | Invoice notes |
 | `--terms` | string | Payment terms text |
 | `--json` | flag | JSON output |
@@ -2224,7 +2227,8 @@ ct invoice recurring update TEMPLATE_ID [options]
 | `--active/--inactive` | flag | Activate or deactivate |
 | `--auto-send/--no-auto-send` | flag | Auto-send setting |
 | `--payment-terms` | integer | Payment terms in days |
-| `--group-by`, `-g` | string | Group by setting |
+| `--group-by`, `-g` | string | How to display hours (see `ct invoice create`) |
+| `--details` | string | With `detailed`: what each line shows |
 | `--notes` | string | Invoice notes |
 | `--json` | flag | JSON output |
 

{crowdtime_cli-0.22.0 → crowdtime_cli-0.23.0}/src/crowdtime_cli/skills/crowdtime/references/workflows.md

@@ -330,7 +330,7 @@ When a project uses per-person billing, grouping the invoice by user gives clien
 
 ```bash
 # Create invoice grouped by team member
-ct invoice create --client "Acme Corp" --period last-month --group-by user --payment-terms net30
+ct invoice create --client "Acme Corp" --period last-month --group-by person --payment-terms net30
 
 # Add a line item with a discount (e.g. 2 hours courtesy)
 ct invoice add-item <invoice-id> --desc "Extra support" --qty 10 --rate 150 --discount-type hours --discount-value 2