What's new in tl v0.9.8: when the server says no, it now says why — and what to do about it

A new release of the tl CLI is out today: v0.9.8. The whole release is about one thing: when something doesn’t work, the CLI now shows you (and your AI agent) the same explanation the server actually wrote — instead of collapsing four different situations into one canned line. Nothing about how you ask questions changes; the answers you get when things go sideways are dramatically more useful.

Run tl update and your next session picks it up.

Rate limits and quotas now name themselves

The most common frustration this release fixes: you’d hit a limit, and tl would say “Rate limited. Please wait and try again.” — which was true, but told you nothing about which limit, how much of it you’d used, or the fastest way back to working.

That’s gone. When the server refuses with a 429, you now see the server’s own detail: which cap you hit (a session-quota cap, a premium-data cap, an account-wide cap), how much you’ve spent against it, when it resets, and — if you’re a team member without a metered seat — who on your team can assign you one.

The premium-data quota used to be worse than that: it would just return an empty result set, so a legitimate query looked like it had “no data”. Now it refuses cleanly and tells you exactly why.

Prompts that land nicely here:

• “I got a 429 on my last query — read the error carefully and tell me which cap I hit and when it frees up.”
• “Am I close to any of my caps? Check tl balance and let me know if I should pace my next batch of queries.”
• “If I keep getting quota-blocked, who should I ask for a metered seat? The refusal message named someone.”

When you run out of credits, the message finally fits your plan

Before v0.9.8, hitting 402 (insufficient credits) always printed the same top-up pitch — even for subscription organizations, whose real options include waiting for the next scheduled top-up rather than paying for a one-off refill.

Now the server’s message prints verbatim. Prepaid users still see the “buy more credits” path, along with the tl credits buy shortcut. Subscription users see their actual menu, including the next-top-up date. Nobody sees copy that doesn’t apply to them.

If you or your agent hits a 402, the message itself now tells you which choice makes sense — no context-switching to your billing dashboard just to figure out the shape of your subscription.

Access-denied errors stop pretending it’s a plan issue

The old CLI slapped “Your plan may not include access to this resource.” onto every 403, including ones that had nothing to do with plans (a superuser-only endpoint, a per-record permission, a wrong org context). The line was misleading, and it made a lot of “why am I locked out?” conversations start in the wrong place.

The stale line is gone. You now see the real reason the server rejected the call — which is much easier for your agent to reason about, and much easier for you to hand to support if you need help.

Every refusal now carries the server’s helpful hint

The API often ships a hint field alongside a refusal — the next thing you might try, a link to the right doc page, a note about what changed. In earlier releases, only generic errors surfaced it. Refusals for hitting a cap, running out of credits, or lacking access dropped the hint silently.

v0.9.8 renders hints on every kind of refusal. If the server has advice attached, you (and your agent) get to see it.

tl balance grew up

tl balance used to answer one question: “how many credits do I have?” That’s still there — but if the server also has usage information for you (your current session-quota percentage, or an explanation of why metered calls will refuse because you don’t have a seat), it now prints that too.

The information had been available all along, but only in --json mode — you had to know to look for it. Now it’s right there in the default output, in a warning-colored line under your balance. If you’re on a shared org account and metered features refuse for you, the same command tells you why and who can fix it.

Prompt shapes that make this useful:

• “Check my balance and quota status. Anything I need to know before running today’s outreach batch?”
• “Am I on a metered seat? If not, tell me exactly what won’t work and who I need to ping.”

Silent gaps in results become explicit “withheld” notices

If a query normally returns premium fields — full transcripts, brand-mention detections, audience demographics — and your plan tier doesn’t include them, previous releases would return the record with those fields simply missing. That looked identical to “the data doesn’t exist,” which is a genuinely different situation, and it caused real analysis mistakes.

Now, when premium fields are withheld from a successful response, the CLI prints a clear note on stderr telling you what was held back and why. Your agent can see it and adjust its analysis; you can see it and know whether to escalate for an upgrade.

Billing links now go somewhere useful

The last two stale billing URLs in the CLI (a /billing/cli link and a /settings/billing link) both pointed at pages that no longer exist. They now go to the same https://app.thoughtleaders.io/billing destination as every other billing link in the tool. If you or your account manager ever forwards someone a “you’re out of credits” screenshot with a link in it, that link now works.

Bonus: fewer slow raw-SQL detours on channel names

Under the hood there’s one more polish worth naming: the docs your agent reads when it drops into raw SQL now explain the correct case-insensitive channel-name lookup pattern, along with the two common wrong turns it kept hitting. Case-insensitive channel-name searches that used to take up to 30 seconds are now index-served — which means a research prompt that hunts for a channel by name doesn’t randomly stall for half a minute anymore.

You’ll feel this indirectly: a deep-dive that used to have an occasional slow patch just… doesn’t.

Updating

Run tl update to grab v0.9.8, or keep working — the auto-updater catches you up on your next call. tl changelog shows the running log of what’s landed since your last release.

If clarity in error messages is the thing that makes AI agents genuinely usable — and it is — this release is worth pulling right away.