thoughtleaders-cli 0.9.3__tar.gz → 0.9.7__tar.gz

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.9.2",
+  "version": "0.9.7",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/.github/workflows/ci.yml

@@ -26,8 +26,8 @@ jobs:
         # Matches `requires-python = ">=3.12"`.
         python-version: ["3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v6
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Sync locked dependencies

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/.github/workflows/cli-integration.yml

@@ -29,8 +29,8 @@ jobs:
     name: Live read-only CLI tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Sync locked dependencies (installs the `tl` CLI)

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/.github/workflows/python-publish.yml

@@ -11,7 +11,7 @@ jobs:
   release-build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: "3.12"

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/API.md

@@ -142,6 +142,8 @@ Useful for verifying the API key resolves to the user you expect before kicking
 
 `GET /balance` — credit balance plus the last 10 metered calls for the org. Free.
 
+`balance` is the combined total of two pools: `topup_balance` (plan-granted credits, reset to the plan allowance each top-up period, spent first) and `purchased_balance` (bought credits — they survive top-up resets, are spent last, and keep working after the per-user session quota is exhausted).
+
 ```bash
 curl -sS "$TL_API_BASE/balance" \
   -H "Authorization: Bearer $TL_API_KEY" \
@@ -155,6 +157,8 @@ print(get('/balance'))
 ```json
 {
   "balance": 9995.88,
+  "topup_balance": 8995.88,
+  "purchased_balance": 1000.00,
   "allow_overage": false,
   "recent_usage": [
     {

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.9.3
+Version: 0.9.7
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli
@@ -284,6 +284,21 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 - **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
+## Distributed skills
+
+Beyond the bundled set above, an organization can be granted additional skills that aren't part of a CLI release — `tl skill` fetches and installs them on demand into the same directories `tl setup` uses (Claude Code's standalone skills directory, OpenCode's skills directory, and the directory shared by Gemini and Codex), so every supported agent picks them up automatically.
+
+```bash
+tl skill list                 # skills available to your organization, with installed/latest versions
+tl skill list --all           # full catalog (full-access accounts only)
+tl skill download my-skill    # fetch and install into every AI-agent skill directory
+tl skill download my-skill --force   # overwrite a directory tl doesn't already manage
+tl skill update                # refresh every downloaded skill to its latest version
+tl skill remove my-skill        # uninstall a downloaded skill
+```
+
+A directory `tl skill download` doesn't already manage (no prior `tl`-managed install there) is left alone unless `--force` is passed — it never overwrites a skill you installed some other way. `tl` warns once a day, on any command, when a downloaded skill has a newer version available. `tl setup` and self-update re-syncs also respect these directories: a downloaded skill is never rmtree'd or overwritten, even if its name collides with a bundled skill.
+
 ## Output Formats
 
 By default, output is a styled table in the terminal and JSON when piped.

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/README.md

@@ -256,6 +256,21 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 - **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
+## Distributed skills
+
+Beyond the bundled set above, an organization can be granted additional skills that aren't part of a CLI release — `tl skill` fetches and installs them on demand into the same directories `tl setup` uses (Claude Code's standalone skills directory, OpenCode's skills directory, and the directory shared by Gemini and Codex), so every supported agent picks them up automatically.
+
+```bash
+tl skill list                 # skills available to your organization, with installed/latest versions
+tl skill list --all           # full catalog (full-access accounts only)
+tl skill download my-skill    # fetch and install into every AI-agent skill directory
+tl skill download my-skill --force   # overwrite a directory tl doesn't already manage
+tl skill update                # refresh every downloaded skill to its latest version
+tl skill remove my-skill        # uninstall a downloaded skill
+```
+
+A directory `tl skill download` doesn't already manage (no prior `tl`-managed install there) is left alone unless `--force` is passed — it never overwrites a skill you installed some other way. `tl` warns once a day, on any command, when a downloaded skill has a newer version available. `tl setup` and self-update re-syncs also respect these directories: a downloaded skill is never rmtree'd or overwritten, even if its name collides with a bundled skill.
+
 ## Output Formats
 
 By default, output is a styled table in the terminal and JSON when piped.

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.9.3"
+version = "0.9.7"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/skills/tl/SKILL.md

@@ -217,6 +217,8 @@ tl snapshots channel <id>              # Channel metrics over time (Firebolt-bac
 tl snapshots video <id> --channel <id> # Video view curve (--channel required!)
 tl reports                             # List saved reports
 tl reports run <id>                    # Run a saved report
+tl reports link <id> --source <id> --entity <e> [--type include|exclude] [--source-side included|excluded]  # Link another report in as a live entity source
+tl reports unlink <id> --source <id> [--entity <e>] [--type include|exclude]  # Remove report links (all from that source unless narrowed)
 tl <entity> comment-list <id>          # List comments on a sponsorship/channel/brand/upload
 tl <entity> comment-add <id> "msg"     # Add a comment
 tl <entity> comment-edit <comment-id> "msg"  # Edit own comment (author or superuser)
@@ -251,9 +253,8 @@ contact field:
 
 The channel's full email archive (`all_emails` — a JSON object keyed by email address,
 each value recording when and where the address was found) is **not editable here**;
-sending it returns a 400. It is append-only: new addresses are added with the
-internal CLI's `tl-internal channels add-email` command (superuser-only), which never
-modifies or removes existing entries.
+sending it returns a 400. It is append-only and managed through an internal-only
+process that never modifies or removes existing entries — not available via this CLI.
 
 **Profile notes.** `tl profiles update` (superuser only) edits a brand/publisher profile's
 **`superuser_notes`** — the internal free-text notes field on the customer record
@@ -262,6 +263,66 @@ clear. This is currently the only editable profile field; anything else returns
 the editable surface. Use it for account-handling notes meant for the internal team — it is
 never shown to the customer.
 
+**Report linking.** `tl reports link` attaches another report to a report as a **live**
+include/exclude entity source — the target report's results are filtered by the source
+report's entities (channels, brands, articles, or sponsorships) and stay in sync as the
+source changes. This is the "include/exclude entities from another report" feature the
+web UI offers, and it differs from `tl bulk-import`, which copies a **frozen snapshot**
+of IDs. `--type` defaults to `include`; `--source-side` defaults to `included` (pass
+`excluded` to pull the source report's excluded entities instead of its results).
+Requires owning the target report (or full access), and the source report must be
+visible to you. Linking a report to itself, an exact duplicate link, or an unknown key
+comes back as a 400.
+
+`tl reports unlink` removes links: with only `--source`, every link pulling from that
+source report is removed; add `--entity` and/or `--type` to remove just the matching
+one. No matching link comes back as a 404, never a silent no-op.
+
+```bash
+tl reports link 1234 --source 5678 --entity channels                 # include source's channels
+tl reports link 1234 --source 5678 --entity brands --type exclude    # exclude source's brands
+tl reports unlink 1234 --source 5678                                 # remove all links from 5678
+tl reports unlink 1234 --source 5678 --entity brands --type exclude  # remove one specific link
+```
+
+### Profile memory
+
+Profile memory is the free-text summary of who a user is and what they want from
+sponsorships. The onboarding interview writes it first; `tl memory` keeps it current
+afterwards. **This is the standard way to update user data** — prefer it over any
+direct database write.
+
+```bash
+tl memory show                            # Your memory + the preferences derived from it (free)
+tl memory show --profile-id <id>          # Someone else's memory (full-access only) (free)
+tl memory add "<fact>"                    # Fold one new fact into the existing memory (free)
+tl memory set "<blob>"                    # Replace the memory wholesale (free)
+tl memory set --from-file <path>          # Same, reading the text from a file (free)
+```
+
+Examples:
+```bash
+tl memory show --profile-id 8871
+tl memory add "Stopped doing finance ads. Now targeting 18-24 in the US."
+tl memory set --from-file ./memory.txt
+```
+
+`add` is the verb to reach for almost every time: the new fact is folded into the
+existing memory, keeping what's still true and replacing only what the fact
+contradicts. Never read the memory, edit it yourself and write it back with `set` when
+`add` would do — one `add` per fact is the whole interface. `add` takes noticeably
+longer than the other two; that is expected, so let it finish rather than retrying,
+because a repeated `add` can land twice. A fact is one statement, not a document:
+anything past 4,000 characters is rejected, so split a long update into several `add`
+calls rather than sending it as one.
+
+`set` replaces the memory wholesale and, unlike `add`, accepts a short replacement for
+a long memory — treat it as the repair hatch for when a merge has damaged a memory,
+not as a routine update path. Blank replacement text is refused rather than erasing the
+memory, and text beyond 50,000 characters is not kept. `add` and `set` always write to
+the **caller's own** profile regardless of permissions; only `show --profile-id` can
+reach someone else's, and that's full-access only.
+
 ### Creating and vetting sponsorships
 
 This is the end-to-end workflow for proposing a sponsorship, then moving it through the funnel as the two sides respond. Three create commands plus `tl sponsorships update` cover every state transition the CLI exposes.
@@ -503,6 +564,21 @@ tl changelog since v0.4.10             # Notes from v0.4.10 to latest
 tl changelog --md > CHANGELOG.md       # Capture for a doc
 ```
 
+#### Distributed skills — beyond the bundled set
+
+An organization can be granted additional skills that aren't part of a CLI release. `tl skill` fetches and installs them on demand into the same directories `tl setup` uses (Claude Code's standalone skills directory, OpenCode's skills directory, and the directory shared by Gemini and Codex), so every supported agent picks them up automatically — no restart or reconfiguration needed beyond re-reading the skill listing.
+
+```bash
+tl skill list                          # Skills available to your org, with installed/latest versions (free)
+tl skill list --all                    # Full catalog (full-access accounts only)
+tl skill download <name>                # Fetch and install into every AI-agent skill directory on this machine
+tl skill download <name> --force        # Overwrite a directory tl doesn't already manage
+tl skill update                         # Refresh every downloaded skill to its latest version
+tl skill remove <name>                  # Uninstall a downloaded skill
+```
+
+If a user asks to find, add, or refresh a skill by capability ("is there a skill for X", "get me the latest Y skill"), check `tl skill list` before saying no — the bundled set isn't the whole catalog. `tl skill download` never overwrites a directory it doesn't already manage unless `--force` is passed, so it's safe to run without clobbering a manually-installed skill of the same name. `tl` warns once a day, on any command, when a downloaded skill has a newer version available — surface that nag to the user rather than silently ignoring it, and offer to run `tl skill update`.
+
 #### Channel & video discovery — pick the path for the question shape
 
 Four first-class paths, each with a different signal. **Pick by the SHAPE of the user's question, not by habit.** "Recommender first" is the right default only for path 2 — for paths 1, 3, and 4 the recommender is the wrong tool.

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/skills/tl/references/postgres-schema.md

@@ -25,6 +25,7 @@ The profile table is tightly coupled with the brand table for media buyers, so m
 > - ❌ `youtube_id` (on channel) — use `external_channel_id`.
 > - ❌ `msn_join_date` (on channel) — use `media_selling_network_join_date`.
 > - ❌ `mbn_join_date` (on profile) — use `media_buying_network_join_date`.
+> - ❌ `url` — renamed to `urls` (array) by migration 0010 (2026-07-16, "AdLink.url becomes urls"). A sponsorship can carry several URLs now; use `urls` — e.g. `urls[1]` for the first entry, or `array_to_string(urls, ', ')` to flatten.
 
 #### Key Columns for the thoughtleaders_adlink table
 
@@ -58,6 +59,7 @@ The profile table is tightly coupled with the brand table for media buyers, so m
 | `performance_grade` | int | Performance rating (see business-glossary) |
 | `article_id` | varchar | Compound `<channel_id>:<youtube_id>` — links to ES `_id` and ES `id` field |
 | `created_where` | varchar | What mechanism / software / agent created the record |
+| `urls` | varchar(600)[] (array) | Destination/reference URLs for the sponsorship. ⚠️ Renamed from the old singular `url` column by migration 0010 (2026-07-16) — a sponsorship can carry several URLs now. Never NULL (empty array `{}` when none set). Use `urls[1]` for "the" URL when a single value is needed, or `array_to_string(urls, ', ')` to flatten for display. |
 
 #### `publish_status` Constants
 
@@ -204,7 +206,7 @@ A channel can have multiple adspots (different sellers: talent manager, direct,
 
 When composing `SELECT ... FROM thoughtleaders_channel ...`, do not improvise column names from semantic intuition — consult the output of `tl schema pg thoughtleaders_channel` or the column table above. The `tl schema` command is authoritative. Failed guesses return *"column '\<name\>' does not exist"* and cost a round-trip. Recurring problems:
 
-- Subscriber count is in the field named `subscribers`
+- ❌ `reach` — this column does NOT exist on Postgres. Use `subscribers`. (The Elasticsearch channel doc uses `reach` as a legacy alias for the same value — see [elasticsearch-schema.md](elasticsearch-schema.md) — but Postgres never had that name; don't carry the ES field name over when switching to a `tl db pg` query.)
 - Projected views is in the field named `projected_views`
 - ❌ **Suffix/qualifier variants of date columns** (e.g. an `_max` / `latest_` / `_date` form when the canonical column has neither). Date columns  use bare names.
 - ❌ **Platform-name-prefixed ID forms** (e.g. a platform-name prefix when the canonical column uses a neutral `external_` prefix). See the column table for the actual ID column.

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.9.3"
+__version__ = "0.9.7"

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/src/tl_cli/client/http.py

@@ -23,11 +23,11 @@ class TLClient:
             },
         )
 
-    def get(self, path: str, params: dict | None = None) -> dict:
-        return self._request("GET", path, params=params)
+    def get(self, path: str, params: dict | None = None, timeout: float | None = None) -> dict:
+        return self._request("GET", path, params=params, timeout=timeout)
 
-    def post(self, path: str, json_body: dict | None = None) -> dict:
-        return self._request("POST", path, json_body=json_body)
+    def post(self, path: str, json_body: dict | None = None, timeout: float | None = None) -> dict:
+        return self._request("POST", path, json_body=json_body, timeout=timeout)
 
     def patch(self, path: str, json_body: dict | None = None) -> dict:
         return self._request("PATCH", path, json_body=json_body)
@@ -38,20 +38,24 @@ class TLClient:
         path: str,
         params: dict | None = None,
         json_body: dict | None = None,
+        timeout: float | None = None,
     ) -> dict:
         headers = self._auth_headers()
+        # Only overrides the client's default timeout when the caller asks
+        # for one — passing `timeout=None` through to httpx means "no
+        # timeout", not "use the default", so it's omitted entirely here.
+        request_kwargs = {"params": params, "json": json_body, "headers": headers}
+        if timeout is not None:
+            request_kwargs["timeout"] = timeout
 
-        response = self._client.request(
-            method, path, params=params, json=json_body, headers=headers
-        )
+        response = self._client.request(method, path, **request_kwargs)
 
         # On 401, try refreshing the token once
         if response.status_code == 401:
             headers = self._refresh_and_get_headers()
             if headers:
-                response = self._client.request(
-                    method, path, params=params, json=json_body, headers=headers
-                )
+                request_kwargs["headers"] = headers
+                response = self._client.request(method, path, **request_kwargs)
 
         if response.status_code >= 400:
             detail = self._extract_detail(response)

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/src/tl_cli/commands/balance.py

@@ -44,6 +44,12 @@ def balance(
         allow_overage = data.get("allow_overage", False)
 
         console.print(f"\n[bold]Credit Balance:[/bold] [cyan]{balance_val}[/cyan] credits")
+        # Older servers return only the combined balance; newer ones split it
+        # into the plan-granted (top-up) pool and the purchased pool.
+        topup_val = data.get("topup_balance")
+        purchased_val = data.get("purchased_balance")
+        if topup_val is not None and purchased_val is not None:
+            console.print(f"[dim]Plan (top-up) credits: {topup_val} · Purchased: {purchased_val}[/dim]")
         if allow_overage:
             console.print("[dim]Overage: enabled[/dim]")
 

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/src/tl_cli/commands/db.py

@@ -99,9 +99,11 @@ def pg_cmd(
     Common traps — check before writing SQL:
 
     - Column names follow the current schema: subscribers, projected_views,
-      scheduled_date, is_tpp, advertiser_profile_id, views_guarantee — NOT the
-      older reach / impression / send_date / is_tl_channel / creator_profile_id
-      / impressions_guarantee.
+      scheduled_date, is_tpp, advertiser_profile_id, views_guarantee, url (the
+      channel's own URL) — NOT the older reach / impression / send_date /
+      is_tl_channel / creator_profile_id / impressions_guarantee / channel_url.
+    - thoughtleaders_adlink has no bare `url` column — the live sponsored-video
+      URL is `media_url`.
     - The sponsorship table (thoughtleaders_adlink) hides its relations behind
       joins: no channel_id/channel_name (join thoughtleaders_adspot via
       ad_spot_id, then thoughtleaders_channel) and no brand_id (join

thoughtleaders_cli-0.9.7/src/tl_cli/commands/memory.py

@@ -0,0 +1,149 @@
+"""tl memory — read and update your profile memory.
+
+Your profile memory is the free-text summary of who you are and what you want from
+sponsorships. The onboarding interview writes it first; these commands are how it
+stays current afterwards.
+"""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markup import escape as rich_escape
+
+from tl_cli._typer_utils import AlphaSortedTyperGroup
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.output.formatter import detect_format, output_single
+
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Your profile memory (show; add a fact; replace)")
+
+# `add` folds the fact into the existing memory with a model call whose duration
+# scales with how much memory there is to rewrite, so it can run far past the
+# client's 30s default. `set` is a plain replace and needs no extra room.
+_ADD_TIMEOUT_SECONDS = 180.0
+
+
+@app.command("show")
+def show_cmd(
+    profile_id: int | None = typer.Option(None, "--profile-id", help="Another profile's memory (full-access only)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Show your profile memory and the preferences derived from it.
+
+    Examples:
+        tl memory show
+        tl memory show --json
+        tl memory show --profile-id 8871
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    params = {"profile_id": profile_id} if profile_id is not None else {}
+
+    client = get_client()
+    try:
+        data = client.get("/memory", params=params)
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("add")
+def add_cmd(
+    fact: str = typer.Argument(..., help="One new fact about you"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Fold one new fact into your profile memory.
+
+    The fact is merged into what's already there — everything still true is kept,
+    and only what the new fact contradicts is replaced. Always writes to your own
+    profile.
+
+    Examples:
+        tl memory add "We stopped doing finance sponsorships."
+        tl memory add "Now targeting 18-24 in the US."
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    if not fact.strip():
+        Console(stderr=True).print("[red]Error:[/red] fact cannot be empty.")
+        raise typer.Exit(1)
+
+    client = get_client()
+    try:
+        data = client.post("/memory", json_body={"fact": fact.strip()}, timeout=_ADD_TIMEOUT_SECONDS)
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("set")
+def set_cmd(
+    memory: str | None = typer.Argument(None, help="The full replacement text"),
+    from_file: Path | None = typer.Option(None, "--from-file", help="Read the replacement text from a file"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Replace your profile memory wholesale.
+
+    The repair hatch for when a merge has gone wrong — unlike `add`, this is not
+    length-guarded, so it will happily replace a long blob with a short one.
+    Prefer `add` for ordinary updates.
+
+    Examples:
+        tl memory set "Runs a finance channel. Avoids crypto."
+        tl memory set --from-file ./memory.txt
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    err = Console(stderr=True)
+
+    if memory is not None and from_file is not None:
+        err.print("[red]Error:[/red] pass either the replacement text or --from-file, not both.")
+        raise typer.Exit(1)
+    if memory is None and from_file is None:
+        err.print("[red]Error:[/red] pass the replacement text, or --from-file to read it from a file.")
+        raise typer.Exit(1)
+
+    if from_file is not None:
+        try:
+            # utf-8-sig, not utf-8: an editor that writes a byte-order mark leaves it
+            # as the first character of the text, where it is not whitespace, survives
+            # the strip below, and is stored invisibly at the head of the memory.
+            memory = from_file.read_text(encoding="utf-8-sig")
+        # A non-text file raises UnicodeDecodeError, a ValueError rather than an
+        # OSError. The path and the error text are escaped because a bracket in
+        # either would abort on a markup error and lose the message itself.
+        except (OSError, UnicodeDecodeError) as exc:
+            err.print(f"[red]Error:[/red] could not read {rich_escape(str(from_file))}: {rich_escape(str(exc))}")
+            raise typer.Exit(1)
+
+    # A blank replacement erases the whole memory, and the two ways to arrive at one
+    # — a stray empty argument, or a --from-file that was never written — are both
+    # mistakes rather than an intent to erase.
+    memory = (memory or "").strip()
+    if not memory:
+        source = f"{rich_escape(str(from_file))} is empty" if from_file is not None else "the replacement text is empty"
+        err.print(f"[red]Error:[/red] {source}; that would erase your whole memory.")
+        err.print("Pass the text you want stored, or use [bold]tl memory add[/bold] to change one thing at a time.")
+        raise typer.Exit(1)
+
+    client = get_client()
+    try:
+        data = client.post("/memory", json_body={"memory": memory})
+        output_single(data, fmt)
+        # A replacement past the size limit is kept only up to it. The stored length
+        # is in the output either way, but nothing there says text went missing.
+        stored = data.get("profile_memory")
+        if isinstance(stored, str) and len(stored) < len(memory):
+            err.print(
+                f"[bold yellow]Warning:[/bold yellow] [yellow]stored {len(stored):,} of "
+                f"{len(memory):,} characters — the rest was past the size limit.[/yellow]"
+            )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

{thoughtleaders_cli-0.9.3 → thoughtleaders_cli-0.9.7}/src/tl_cli/commands/reports.py

@@ -672,3 +672,109 @@ def update_report(
         handle_api_error(e)
     finally:
         client.close()
+
+
+LINK_ENTITIES = ("channels", "brands", "articles", "sponsorships")
+LINK_TYPES = ("include", "exclude")
+LINK_SOURCE_SIDES = ("included", "excluded")
+
+
+@app.command("link")
+def link_report(
+    report_id: int = typer.Argument(..., help="Target report ID (the report being filtered)"),
+    source: int = typer.Option(..., "--source", "-s", help="Source report ID whose entities are pulled in"),
+    entity: str = typer.Option(..., "--entity", "-e", help=f"Entity type: one of {', '.join(LINK_ENTITIES)}"),
+    filter_type: str = typer.Option(
+        "include", "--type", "-t", help="How the source acts on the target: include or exclude"
+    ),
+    source_side: str = typer.Option(
+        "included",
+        "--source-side",
+        help="Pull the source report's results ('included', default) or its excluded entities ('excluded')",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Link another report into this report as an include/exclude entity source.
+
+    The target report's results are then filtered by the source report's
+    entities of the given type — the same linking the web UI offers, kept
+    in sync automatically (unlike a bulk-import snapshot).
+
+    Examples:
+        tl reports link 1234 --source 5678 --entity channels --type include
+        tl reports link 1234 --source 5678 --entity brands --type exclude
+    """
+    if entity not in LINK_ENTITIES:
+        err.print(f"[red]--entity must be one of: {', '.join(LINK_ENTITIES)}[/red]")
+        raise typer.Exit(2)
+    if filter_type not in LINK_TYPES:
+        err.print(f"[red]--type must be one of: {', '.join(LINK_TYPES)}[/red]")
+        raise typer.Exit(2)
+    if source_side not in LINK_SOURCE_SIDES:
+        err.print(f"[red]--source-side must be one of: {', '.join(LINK_SOURCE_SIDES)}[/red]")
+        raise typer.Exit(2)
+
+    fmt = detect_format(json_output, False, False, toon_output)
+    client = get_client()
+    try:
+        data = client.post(
+            f"/reports/{report_id}/link",
+            json_body={
+                "source_report_id": source,
+                "entity": entity,
+                "filter_type": filter_type,
+                "campaign_entity_type": source_side,
+            },
+        )
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("unlink")
+def unlink_report(
+    report_id: int = typer.Argument(..., help="Target report ID (the report holding the link)"),
+    source: int = typer.Option(..., "--source", "-s", help="Source report ID to unlink"),
+    entity: str | None = typer.Option(
+        None, "--entity", "-e", help=f"Only remove links of this entity type: one of {', '.join(LINK_ENTITIES)}"
+    ),
+    filter_type: str | None = typer.Option(
+        None, "--type", "-t", help="Only remove links of this type: include or exclude"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Remove a report link created with `tl reports link`.
+
+    Without --entity/--type, removes every link pulling from the source
+    report. Narrow with --entity and/or --type to remove a specific one.
+
+    Examples:
+        tl reports unlink 1234 --source 5678
+        tl reports unlink 1234 --source 5678 --entity channels --type exclude
+    """
+    if entity is not None and entity not in LINK_ENTITIES:
+        err.print(f"[red]--entity must be one of: {', '.join(LINK_ENTITIES)}[/red]")
+        raise typer.Exit(2)
+    if filter_type is not None and filter_type not in LINK_TYPES:
+        err.print(f"[red]--type must be one of: {', '.join(LINK_TYPES)}[/red]")
+        raise typer.Exit(2)
+
+    body: dict = {"source_report_id": source}
+    if entity is not None:
+        body["entity"] = entity
+    if filter_type is not None:
+        body["filter_type"] = filter_type
+
+    fmt = detect_format(json_output, False, False, toon_output)
+    client = get_client()
+    try:
+        data = client.post(f"/reports/{report_id}/unlink", json_body=body)
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()