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

{crowdtime_cli-0.4.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.4.0 → crowdtime_cli-0.5.0}/PKG-INFO

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.4.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.4.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.4.0"
+__version__ = "0.5.0"

{crowdtime_cli-0.4.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.4.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.4.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.4.0 → crowdtime_cli-0.5.0}/src/crowdtime_cli/skills/crowdtime/SKILL.md

@@ -208,6 +208,23 @@ 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

{crowdtime_cli-0.4.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
@@ -1072,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.4.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)
 
 ---
@@ -627,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