crowdtime-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/.gitignore

@@ -58,3 +58,4 @@ RECOVERY.md
 coolify_deployment.md
 pypi_deployment.md
 sentry-workflow.md
+linear-workflow.md

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.3.0
+Version: 0.5.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
@@ -118,7 +118,9 @@ ct report --week
 | `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 |
+| `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
 

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/README.md

@@ -84,7 +84,9 @@ ct report --week
 | `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 |
+| `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
 

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/pyproject.toml

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

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/__init__.py

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

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/client.py

@@ -135,6 +135,22 @@ class CrowdTimeClient:
             console.print("[red]Permission denied.[/red] You don't have access to this resource.")
             raise SystemExit(1)
 
+        if response.status_code == 402:
+            try:
+                detail = response.json()
+            except Exception:
+                detail = {}
+            msg = (
+                detail.get("detail", "")
+                if isinstance(detail, dict)
+                else str(detail)
+            ) or "Your organization's subscription is inactive."
+            console.print(
+                f"[yellow]{msg}[/yellow]\n"
+                "Run [bold]ct billing portal[/bold] to update your billing."
+            )
+            raise APIError(msg, status_code=402, detail=detail)
+
         if response.status_code == 404:
             raise APIError("Not found", status_code=404)
 

crowdtime_cli-0.5.0/src/crowdtime_cli/commands/billing_cmd.py

@@ -0,0 +1,446 @@
+"""Billing commands: status, portal, plan, reactivate, events."""
+
+from __future__ import annotations
+
+import webbrowser
+from decimal import Decimal
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from ..client import APIError, CrowdTimeClient
+from ..formatters import format_error, format_success, print_json
+
+app = typer.Typer(name="billing", help="Manage subscription and billing.")
+console = Console()
+
+
+# ─── Helpers ──────────────────────────────────────────────────────
+
+
+STATUS_COLORS = {
+    "active": "green",
+    "trialing": "blue",
+    "past_due": "red",
+    "unpaid": "red",
+    "canceled": "yellow",
+    "paused": "yellow",
+    "incomplete": "yellow",
+    "incomplete_expired": "red",
+}
+
+STATUS_LABELS = {
+    "active": "ACTIVE",
+    "trialing": "TRIALING",
+    "past_due": "PAST DUE",
+    "unpaid": "UNPAID",
+    "canceled": "CANCELED",
+    "paused": "PAUSED",
+    "incomplete": "INCOMPLETE",
+    "incomplete_expired": "EXPIRED",
+}
+
+PLAN_LABELS = {
+    "monthly": "Monthly",
+    "annual": "Annual",
+}
+
+
+def _cents_to_dollars(cents: int | str | None) -> Decimal:
+    """Convert an amount in cents to dollars."""
+    if cents is None:
+        return Decimal("0")
+    try:
+        return Decimal(str(cents)) / Decimal("100")
+    except Exception:
+        return Decimal("0")
+
+
+def _format_currency(amount: Decimal) -> str:
+    """Format a Decimal dollar amount for display."""
+    return f"${amount:,.2f}"
+
+
+def _format_date(date_str: str | None) -> str:
+    """Format an ISO date string for display (YYYY-MM-DD)."""
+    if not date_str:
+        return ""
+    # Handle datetime strings by taking just the date part
+    return date_str[:10]
+
+
+# ─── Commands ─────────────────────────────────────────────────────
+
+
+@app.callback(invoke_without_command=True)
+def billing_default(
+    ctx: typer.Context,
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show subscription status or manage billing."""
+    if ctx.invoked_subcommand is None:
+        status(output_json=output_json)
+
+
+@app.command("status")
+def status(
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show current subscription status.
+
+    Displays plan, seats, pricing, and next billing date.
+
+    Examples:
+        ct billing
+        ct billing status
+        ct billing status --json
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        data = client.get("/billing/")
+    except APIError as e:
+        if e.status_code == 402:
+            console.print(
+                "[yellow]No active subscription.[/yellow] "
+                "Run [bold]ct billing portal[/bold] to manage your billing."
+            )
+            raise typer.Exit(1)
+        if e.status_code == 404:
+            console.print(
+                "[dim]No subscription found for this organization.[/dim]\n"
+                "Run [bold]ct billing checkout[/bold] to start a free trial (owner only)."
+            )
+            raise typer.Exit(1)
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json(data)
+        return
+
+    sub_status = data.get("status", "unknown")
+    plan = data.get("plan", "")
+    seat_count = data.get("seat_count", 0)
+
+    # Amounts come from the serializer in cents
+    base_dollars = _cents_to_dollars(data.get("base_amount"))
+    per_seat_dollars = _cents_to_dollars(data.get("per_seat_amount"))
+    total_dollars = _cents_to_dollars(data.get("total_amount"))
+
+    period_end = _format_date(data.get("current_period_end"))
+    cancel_at_end = data.get("cancel_at_period_end", False)
+    trial_ends = _format_date(data.get("trial_ends_at"))
+
+    # Calculate next billing amount (total * months in period)
+    # For monthly it's the same; for annual it's total * 12
+    if plan == "annual":
+        next_amount = total_dollars * 12
+    else:
+        next_amount = total_dollars
+
+    # Status styling
+    color = STATUS_COLORS.get(sub_status, "yellow")
+    label = STATUS_LABELS.get(sub_status, sub_status.upper())
+
+    # Build the info table (no header, simple key-value)
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Key", style="dim", width=12)
+    table.add_column("Value")
+
+    table.add_row("Status", f"[{color}]{label}[/{color}]")
+    table.add_row("Plan", PLAN_LABELS.get(plan, plan.capitalize()))
+    table.add_row("Seats", str(seat_count))
+    table.add_row("Base", f"{_format_currency(base_dollars)}/mo")
+    table.add_row("Per seat", f"{_format_currency(per_seat_dollars)}/mo")
+    table.add_row("Total", f"{_format_currency(total_dollars)}/mo")
+
+    if sub_status == "trialing" and trial_ends:
+        table.add_row("Trial ends", trial_ends)
+    elif period_end:
+        table.add_row("Next bill", period_end)
+        table.add_row("Next amount", _format_currency(next_amount))
+
+    if cancel_at_end:
+        table.add_row("", "[yellow]Cancels at period end[/yellow]")
+
+    panel = Panel(
+        table,
+        title="[bold]Billing[/bold]",
+        border_style=color,
+        padding=(1, 1),
+    )
+    console.print(panel)
+
+
+@app.command("portal")
+def portal(
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Open the Stripe billing portal in your browser.
+
+    Allows you to update payment methods, view invoices,
+    and manage your subscription. Requires owner or admin role.
+
+    Examples:
+        ct billing portal
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    # Build the return URL pointing to the frontend billing page
+    org_slug = client.org_slug
+    frontend_url = client.config.frontend_url
+    return_url = f"{frontend_url}/{org_slug}/settings/billing"
+
+    try:
+        data = client.post("/billing/portal/", data={"return_url": return_url})
+    except APIError as e:
+        if e.status_code == 403:
+            format_error(
+                "Permission denied. Only organization owners and admins "
+                "can access the billing portal."
+            )
+            raise typer.Exit(1)
+        if e.status_code == 404:
+            format_error(
+                "No subscription found. An organization owner must set up "
+                "billing from the web dashboard first."
+            )
+            raise typer.Exit(1)
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    portal_url = data.get("portal_url", data.get("url", ""))
+
+    if not portal_url:
+        format_error("No portal URL returned from the server.")
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json({"portal_url": portal_url})
+        return
+
+    # Open in default browser
+    webbrowser.open(portal_url)
+
+    format_success("Billing portal opened in your browser.")
+    console.print(f"\n  [dim]URL:[/dim] {portal_url}")
+    console.print("  [dim]If the browser didn't open, copy the URL above.[/dim]")
+
+
+@app.command("checkout")
+def checkout(
+    plan_choice: str = typer.Argument(
+        "monthly", help="Plan to subscribe to: 'monthly' or 'annual'."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Start a new subscription via Stripe Checkout.
+
+    Opens the Stripe Checkout page in your browser to start a free
+    trial or subscribe. Requires owner role.
+
+    Examples:
+        ct billing checkout
+        ct billing checkout annual
+    """
+    plan_choice = plan_choice.lower()
+    if plan_choice not in ("monthly", "annual"):
+        format_error("Plan must be 'monthly' or 'annual'.")
+        raise typer.Exit(1)
+
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    org_slug = client.org_slug
+    frontend_url = client.config.frontend_url
+    billing_url = f"{frontend_url}/{org_slug}/settings/billing"
+
+    try:
+        data = client.post("/billing/checkout/", data={
+            "plan": plan_choice,
+            "success_url": f"{billing_url}?checkout=success",
+            "cancel_url": f"{billing_url}?checkout=canceled",
+        })
+    except APIError as e:
+        if e.status_code == 400:
+            format_error(e.message or "Cannot create checkout session.")
+            raise typer.Exit(1)
+        if e.status_code == 403:
+            format_error("Permission denied. Only the organization owner can start a subscription.")
+            raise typer.Exit(1)
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    checkout_url = data.get("checkout_url", "")
+
+    if not checkout_url:
+        format_error("No checkout URL returned from the server.")
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json({"checkout_url": checkout_url})
+        return
+
+    webbrowser.open(checkout_url)
+
+    format_success("Stripe Checkout opened in your browser.")
+    console.print(f"\n  [dim]URL:[/dim] {checkout_url}")
+    console.print("  [dim]If the browser didn't open, copy the URL above.[/dim]")
+
+
+@app.command("plan")
+def plan(
+    new_plan: str = typer.Argument(
+        ..., help="Plan to switch to: 'monthly' or 'annual'."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Switch billing plan between monthly and annual.
+
+    Requires owner role. The change takes effect immediately with
+    prorated credit for the remainder of the current period.
+
+    Examples:
+        ct billing plan annual
+        ct billing plan monthly
+    """
+    new_plan = new_plan.lower()
+    if new_plan not in ("monthly", "annual"):
+        format_error("Plan must be 'monthly' or 'annual'.")
+        raise typer.Exit(1)
+
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        data = client.patch("/billing/plan/", data={"plan": new_plan})
+    except APIError as e:
+        if e.status_code == 400:
+            format_error(e.message or "Invalid plan change request.")
+            raise typer.Exit(1)
+        if e.status_code == 403:
+            format_error("Permission denied. Only the organization owner can switch plans.")
+            raise typer.Exit(1)
+        if e.status_code == 404:
+            format_error("No subscription found.")
+            raise typer.Exit(1)
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json(data)
+        return
+
+    plan_label = PLAN_LABELS.get(new_plan, new_plan.capitalize())
+    format_success(f"Switched to {plan_label} billing.")
+
+    total = _cents_to_dollars(data.get("total_amount"))
+    if new_plan == "annual":
+        console.print(f"  [dim]Billed annually at {_format_currency(total * 12)}/yr[/dim]")
+    else:
+        console.print(f"  [dim]Billed at {_format_currency(total)}/mo[/dim]")
+
+
+@app.command("reactivate")
+def reactivate(
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Reactivate a canceled subscription.
+
+    Undoes a pending cancellation so the subscription continues
+    at the end of the current billing period. Requires owner role.
+
+    Examples:
+        ct billing reactivate
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        data = client.post("/billing/reactivate/", data={})
+    except APIError as e:
+        if e.status_code == 400:
+            format_error(e.message or "Subscription is not scheduled for cancellation.")
+            raise typer.Exit(1)
+        if e.status_code == 403:
+            format_error("Permission denied. Only the organization owner can reactivate.")
+            raise typer.Exit(1)
+        if e.status_code == 404:
+            format_error("No subscription found.")
+            raise typer.Exit(1)
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json(data)
+        return
+
+    format_success("Subscription reactivated.")
+    period_end = _format_date(data.get("current_period_end"))
+    if period_end:
+        console.print(f"  [dim]Next renewal: {period_end}[/dim]")
+
+
+@app.command("events")
+def events(
+    limit: int = typer.Option(20, "--limit", "-n", help="Number of events to show."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show billing event audit log.
+
+    Displays recent Stripe webhook events processed for this
+    organization. Requires owner role.
+
+    Examples:
+        ct billing events
+        ct billing events -n 50
+        ct billing events --json
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        data = client.get("/billing/events/")
+    except APIError as e:
+        if e.status_code == 403:
+            format_error("Permission denied. Only the organization owner can view billing events.")
+            raise typer.Exit(1)
+        if e.status_code == 404:
+            format_error("No subscription found.")
+            raise typer.Exit(1)
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    # Handle both paginated and flat list responses
+    event_list = data if isinstance(data, list) else data.get("results", data.get("data", []))
+    event_list = event_list[:limit]
+
+    if output_json:
+        print_json(event_list)
+        return
+
+    if not event_list:
+        console.print("[dim]No billing events found.[/dim]")
+        return
+
+    table = Table(title="Billing Events", show_lines=False)
+    table.add_column("Date", style="dim", width=10)
+    table.add_column("Event", width=40)
+    table.add_column("Status", width=10)
+
+    for event in event_list:
+        date = _format_date(event.get("created_at"))
+        event_type = event.get("event_type", "unknown")
+        processed = event.get("processed", False)
+        error = event.get("error", "")
+
+        if error:
+            status_str = "[red]FAILED[/red]"
+        elif processed:
+            status_str = "[green]OK[/green]"
+        else:
+            status_str = "[yellow]PENDING[/yellow]"
+
+        table.add_row(date, event_type, status_str)
+
+    console.print(table)

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/commands/org_cmd.py

@@ -43,7 +43,7 @@ def list_orgs(
         table.add_column("", width=3)
         table.add_column("Name", width=20)
         table.add_column("Slug", width=15)
-        table.add_column("Role", width=10)
+        table.add_column("Role", width=18)
         table.add_column("Members", justify="right", width=8)
 
         for org in orgs:
@@ -113,7 +113,10 @@ def members(
 @app.command()
 def invite(
     email: str = typer.Argument(..., help="Email address to invite."),
-    role: str = typer.Option("member", "--role", "-r", help="Role: admin, manager, member."),
+    role: str = typer.Option(
+        "member", "--role", "-r",
+        help="Role: admin, manager (account), project_manager, member, viewer.",
+    ),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
     """Invite a member to the current organization."""
@@ -132,3 +135,74 @@ def invite(
     except APIError as e:
         format_error(e.message)
         raise typer.Exit(1)
+
+
+@app.command("resend-invite")
+def resend_invite(
+    invitation_id: str = typer.Argument(..., help="Invitation ID to resend."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Resend a pending invitation email."""
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        data = client.post(f"/invitations/{invitation_id}/resend/")
+
+        if output_json:
+            print_json(data)
+        else:
+            format_success("Invitation email resent.")
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+
+@app.command()
+def invitations(
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List pending invitations for the current organization."""
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        data = client.get("/invitations/")
+        inv_list = data if isinstance(data, list) else data.get("results", [])
+
+        if output_json:
+            print_json(inv_list)
+            return
+
+        pending = [i for i in inv_list if i.get("status") == "pending"]
+        if not pending:
+            console.print("[dim]No pending invitations.[/dim]")
+            return
+
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("ID", style="dim")
+        table.add_column("Email", width=25)
+        table.add_column("Role", width=18)
+        table.add_column("Status", width=10)
+        table.add_column("Expires", width=12)
+
+        role_labels = {
+            "owner": "Owner",
+            "admin": "Admin",
+            "manager": "Account Manager",
+            "project_manager": "Project Manager",
+            "member": "Member",
+            "viewer": "Viewer",
+        }
+
+        for inv in pending:
+            table.add_row(
+                inv.get("id", ""),
+                inv.get("email", ""),
+                role_labels.get(inv.get("role", ""), inv.get("role", "")),
+                inv.get("status", ""),
+                inv.get("expires_at", "")[:10] if inv.get("expires_at") else "",
+            )
+
+        console.print(table)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/config.py

@@ -99,6 +99,23 @@ class CrowdTimeConfig:
     def server_url(self) -> str:
         return str(self.get("server.url", "https://api.crowdtime.lat")).rstrip("/")
 
+    @property
+    def frontend_url(self) -> str:
+        """Frontend URL, derived from server URL if not explicitly set.
+
+        Default derivation: https://api.crowdtime.lat → https://app.crowdtime.lat
+        Local dev: http://localhost:8001 → http://localhost:3000
+        """
+        explicit = self.get("server.frontend_url", "")
+        if explicit:
+            return str(explicit).rstrip("/")
+        url = self.server_url
+        if "://api." in url:
+            return url.replace("://api.", "://app.")
+        if "localhost:8001" in url:
+            return url.replace("localhost:8001", "localhost:3000")
+        return url
+
     @property
     def organization(self) -> str:
         return str(self.get("defaults.organization", ""))

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/formatters.py

@@ -362,6 +362,16 @@ def format_report(data: list[dict[str, Any]], group_by: str = "project") -> None
     console.print(table)
 
 
+ROLE_LABELS = {
+    "owner": "Owner",
+    "admin": "Admin",
+    "manager": "Account Manager",
+    "project_manager": "Project Manager",
+    "member": "Member",
+    "viewer": "Viewer",
+}
+
+
 def format_members_table(members: list[dict[str, Any]]) -> None:
     """Display organization members in a table."""
     if not members:
@@ -371,15 +381,17 @@ def format_members_table(members: list[dict[str, Any]]) -> None:
     table = Table(show_header=True, header_style="bold")
     table.add_column("Name", width=20)
     table.add_column("Email", width=25)
-    table.add_column("Role", width=10)
+    table.add_column("Role", width=18)
     table.add_column("Status", width=10)
 
     for m in members:
         status = "[green]Active[/green]" if m.get("is_active", True) else "[dim]Inactive[/dim]"
+        role = m.get("role", "member")
+        role_label = ROLE_LABELS.get(role, role)
         table.add_row(
             m.get("user_name", ""),
             m.get("user_email", ""),
-            m.get("role", "member"),
+            role_label,
             status,
         )
 

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/main.py

@@ -22,6 +22,7 @@ from .models import TimeEntry, User
 from .commands import (
     ai_cmd,
     auth_cmd,
+    billing_cmd,
     clients_cmd,
     config_cmd,
     expense_cmd,
@@ -49,6 +50,7 @@ app = typer.Typer(
 
 # Register command groups
 app.add_typer(auth_cmd.app, name="auth")
+app.add_typer(billing_cmd.app, name="billing")
 app.add_typer(timer_cmd.app, name="timer")
 app.add_typer(log_cmd.app, name="log")
 app.add_typer(projects_cmd.app, name="projects")
@@ -277,6 +279,14 @@ def projects_list_alias(
     projects_cmd.list_projects(archived=archived, output_json=output_json)
 
 
+@app.command("b", hidden=True)
+def billing_alias(
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Alias for 'billing status'."""
+    billing_cmd.status(output_json=output_json)
+
+
 @app.command("ex", hidden=True)
 def expense_list_alias(
     from_date: Optional[str] = typer.Option(None, "--from"),
@@ -301,10 +311,10 @@ def expense_list_alias(
 def _is_known_command(arg: str) -> bool:
     """Check if an argument is a known command or subcommand."""
     known = {
-        "auth", "timer", "log", "projects", "clients", "tasks", "report", "ai",
-        "org", "config", "favorites", "skill", "timesheet", "invoice", "expense",
+        "auth", "billing", "timer", "log", "projects", "clients", "tasks", "report",
+        "ai", "org", "config", "favorites", "skill", "timesheet", "invoice", "expense",
         "status", "s", "t", "ts", "tx",
-        "l", "ll", "r", "p", "ex", "--help", "-h", "--version", "-v", "--json",
+        "l", "ll", "r", "p", "b", "ex", "--help", "-h", "--version", "-v", "--json",
     }
     return arg in known
 

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/skills/crowdtime/SKILL.md

@@ -208,14 +208,44 @@ ct invoice retainer withdrawals <id>               # View withdrawal history
 ct invoice retainer reverse-withdrawal <id> -w <wd-id> -r "reason"  # Reverse a withdrawal
 ```
 
+### Billing
+```bash
+ct billing              # Show subscription status (plan, seats, pricing, next bill)
+ct billing status       # Same as bare ct billing
+ct billing checkout     # Start subscription via Stripe Checkout in browser (owner only)
+ct billing checkout annual  # Start with annual plan
+ct billing portal       # Open Stripe billing portal in browser (admin+ only)
+ct billing plan annual  # Switch to annual billing (owner only)
+ct billing plan monthly # Switch to monthly billing (owner only)
+ct billing reactivate   # Undo a pending cancellation (owner only)
+ct billing events       # View billing event audit log (owner only)
+ct billing events -n 50 # Show last 50 events
+
+# Short alias
+ct b                    # billing status
+```
+
 ### Organizations
 ```bash
 ct org list                             # List your organizations
 ct org switch <slug>                    # Switch active organization
 ct org members                          # List members
+ct org invitations                      # List pending invitations
 ct org invite user@example.com -r member
+ct org invite client@acme.com -r viewer              # External client stakeholder (read-only)
+ct org invite pm@company.com -r project_manager      # Project manager (no financial access)
+ct org invite billing@company.com -r manager          # Account manager (full financial access)
+ct org resend-invite <invitation-id>                  # Resend a pending invitation
 ```
 
+**Role hierarchy** (lowest → highest):
+- **viewer** — external client stakeholder, read-only access scoped to assigned projects
+- **member** — can log time, manage own entries
+- **project_manager** — manage projects, tasks, timesheets, team time; no financial data
+- **manager** (Account Manager) — everything project_manager does + invoices, rates, clients, billing
+- **admin** — manage org settings, members, integrations
+- **owner** — full control, can delete org
+
 ### Configuration
 ```bash
 ct config list                          # Show all config

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/skills/crowdtime/references/commands.md

@@ -11,6 +11,7 @@ Every command, subcommand, argument, flag, and option in the CrowdTime CLI.
 - [ct log](#ct-log)
 - [ct clients](#ct-clients)
 - [ct expense](#ct-expense)
+- [ct billing](#ct-billing)
 - [ct projects](#ct-projects)
 - [ct tasks](#ct-tasks)
 - [ct report](#ct-report)
@@ -471,6 +472,111 @@ Endpoint: `POST /expenses/categories/`
 
 ---
 
+## ct billing
+
+Short alias: `ct b`
+
+### ct billing (bare / status)
+
+```
+ct billing [--json]
+ct billing status [--json]
+ct b [--json]           # alias
+```
+
+Shows subscription status in a Rich panel: status, plan (monthly/annual), seat count, base price, per-seat price, total monthly cost, next billing date, and next billing amount.
+
+**Status colors:**
+| Status | Color |
+|--------|-------|
+| ACTIVE | green |
+| TRIALING | blue |
+| PAST_DUE, UNPAID | red |
+| CANCELED, PAUSED | yellow |
+
+Handles 402 (subscription inactive) and 404 (no subscription) gracefully.
+
+Endpoint: `GET /billing/`
+
+### ct billing portal
+
+```
+ct billing portal [--json]
+```
+
+Opens the Stripe Customer Portal in the default browser. Allows updating payment methods, viewing Stripe invoices, and managing the subscription.
+
+### ct billing checkout
+
+```
+ct billing checkout [monthly|annual] [--json]
+```
+
+Opens Stripe Checkout in the browser to start a new subscription (with free trial). Defaults to monthly plan.
+
+- Requires **owner** role
+- Opens the Stripe-hosted checkout page in the default browser
+- After checkout, redirects to the billing settings page
+- `--json` outputs `{"checkout_url": "..."}` instead of opening the browser
+- Errors if the organization already has an active subscription
+
+Endpoint: `POST /billing/checkout/`
+
+### ct billing portal
+
+- Requires **admin+** role (API enforces this; shows friendly error on 403)
+- Prints the portal URL for manual access if the browser doesn't open
+- `--json` outputs `{"portal_url": "..."}` instead of opening the browser
+
+Endpoint: `POST /billing/portal/`
+
+### ct billing plan
+
+```
+ct billing plan <monthly|annual> [--json]
+```
+
+Switches the billing plan between monthly and annual. The change takes effect immediately with prorated credit for the remainder of the current period.
+
+- Requires **owner** role
+- Shows the new billing amount after switching
+- Errors if already on the target plan
+
+Endpoint: `PATCH /billing/plan/`
+
+### ct billing reactivate
+
+```
+ct billing reactivate [--json]
+```
+
+Undoes a pending cancellation so the subscription continues at the end of the current billing period.
+
+- Requires **owner** role
+- Only works when `cancel_at_period_end` is true
+- Shows the next renewal date after reactivation
+
+Endpoint: `POST /billing/reactivate/`
+
+### ct billing events
+
+```
+ct billing events [--limit/-n N] [--json]
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--limit`, `-n` | int | 20 | Number of events to show |
+| `--json` | flag | | JSON output |
+
+Shows recent Stripe webhook events processed for this organization. Each event shows date, event type, and processing status (OK, FAILED, PENDING).
+
+- Requires **owner** role
+
+Endpoint: `GET /billing/events/`
+
+---
+
 ## ct projects
 
 ### ct projects list
@@ -745,10 +851,33 @@ ct org invite EMAIL [--role/-r ROLE] [--json]
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `--role`, `-r` | string | `admin`, `manager`, `member` (default) |
+| `--role`, `-r` | string | `admin`, `manager`, `project_manager`, `member` (default), `viewer` |
+
+**Roles:**
+- `viewer` — external client stakeholder, read-only access scoped to assigned projects
+- `member` — can log time, manage own entries
+- `project_manager` — manage projects, tasks, timesheets, team time; no financial data (rates, invoices)
+- `manager` — Account Manager: project management + invoices, rates, clients, billing
+- `admin` — manage org settings, members, integrations
 
 Endpoint: `POST /members/invite/`
 
+### ct org invitations
+
+```
+ct org invitations [--json]
+```
+
+Lists pending invitations for the current organization. Endpoint: `GET /invitations/`
+
+### ct org resend-invite
+
+```
+ct org resend-invite INVITATION_ID [--json]
+```
+
+Resends the invitation email for a pending invitation. Endpoint: `POST /invitations/{id}/resend/`
+
 ---
 
 ## ct config
@@ -1049,5 +1178,6 @@ Endpoint: `POST /invoices/retainers/{id}/withdrawals/{wid}/reverse/`
 | `ct ll` | `ct log list` |
 | `ct p` | `ct projects list` |
 | `ct r` | `ct report` |
+| `ct b` | `ct billing status` |
 | `ct ex` | `ct expense` |
 | `ct "text"` | `ct ai parse "text"` |

{crowdtime_cli-0.3.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/skills/crowdtime/references/workflows.md

@@ -15,6 +15,7 @@ Multi-step workflow patterns for real-world time tracking scenarios.
 - [Client Contact Management](#client-contact-management)
 - [Project Budget Tracking](#project-budget-tracking)
 - [Invoicing and Billing](#invoicing-and-billing)
+- [Subscription and Billing](#subscription-and-billing)
 - [Troubleshooting](#troubleshooting)
 
 ---
@@ -173,18 +174,43 @@ ct l -p acme -d 2026-03-05 3h "client meeting"
 ### Onboard a New Team Member
 
 ```bash
-# Invite them
+# Invite a regular team member
 ct org invite newdev@company.com -r member
 
-# They need to:
-# 1. Accept the invitation (via email link)
-# 2. Install CLI: pip install crowdtime-cli
-# 3. Configure:
-#    ct config set server.url https://your-server.com
-#    ct auth login
-#    ct org switch your-org
+# Invite a project manager (can manage projects/tasks/timesheets, no financial access)
+ct org invite pm@company.com -r project_manager
+
+# Invite an account manager (full financial access: invoices, rates, clients)
+ct org invite billing@company.com -r manager
+
+# Invite an external client stakeholder (read-only, scoped to their projects)
+ct org invite client@acme.com -r viewer
+
+# They receive an email with an "Accept Invitation" link
+# New users can sign up with email/password or Google OAuth
 ```
 
+### Manage Invitations
+
+```bash
+# List pending invitations
+ct org invitations
+
+# Resend an invitation email
+ct org resend-invite <invitation-id>
+```
+
+### Role Reference
+
+| Role | Description |
+|------|-------------|
+| `viewer` | External client: read-only, scoped to assigned projects |
+| `member` | Logs time, manages own entries |
+| `project_manager` | Manages projects, tasks, timesheets, team time. No financial data |
+| `manager` | Account Manager: everything above + invoices, rates, clients, billing |
+| `admin` | Manages org settings, members, integrations |
+| `owner` | Full control including org deletion |
+
 ### Check Team Activity
 
 ```bash
@@ -602,6 +628,93 @@ ct invoice retainer withdraw <retainer-id> --invoice <standard-invoice-id> --amo
 
 ---
 
+## Subscription and Billing
+
+### Check Subscription Status
+
+```bash
+# Quick check
+ct billing
+
+# Machine-readable
+ct billing --json
+```
+
+### Start a Subscription
+
+```bash
+# Start a free trial (opens Stripe Checkout in browser)
+ct billing checkout
+
+# Start with annual plan (20% savings)
+ct billing checkout annual
+```
+
+### Manage Subscription via Stripe Portal
+
+```bash
+# Open Stripe billing portal (admin+ only)
+ct billing portal
+
+# From the portal you can:
+# - Update payment method
+# - View past Stripe invoices
+# - Cancel subscription
+```
+
+### Switch Billing Plan
+
+```bash
+# Switch to annual billing (saves 20%)
+ct billing plan annual
+
+# Switch back to monthly
+ct billing plan monthly
+
+# Change takes effect immediately with prorated credit
+```
+
+### Reactivate a Canceled Subscription
+
+```bash
+# If subscription is set to cancel at period end:
+ct billing reactivate
+
+# Verify it's active again
+ct billing
+```
+
+### View Billing Event History
+
+```bash
+# Show recent billing events (webhook audit log)
+ct billing events
+
+# Show more events
+ct billing events -n 50
+
+# Machine-readable
+ct billing events --json
+```
+
+### Handle Subscription Issues
+
+```bash
+# If you see "subscription is inactive" errors on other commands:
+ct billing                # Check current status
+ct billing portal         # Open portal to update payment or resubscribe
+
+# If subscription is canceled but still within billing period:
+ct billing reactivate     # Undo the cancellation
+
+# If you get "permission denied":
+# - billing portal requires admin+ role
+# - plan changes and reactivation require owner role
+# Ask your org owner to manage the subscription.
+```
+
+---
+
 ## Troubleshooting
 
 ### "Not authenticated" Error