Calling Lenses
The examples leave out --catalog.
Passing parameters
Ask hn/top for the second page:
lens call hn/top --params '{"page": 2}'The client checks parameters against the types the lens declares, before anything runs. It does not convert types, so {"page": "2"} fails: page is an integer, and "2" is a string.
Reading the result
Every result has a kind: value, outcome or error. Check it before you read anything else.
value: the lens got the data
{
"kind": "value",
"value": {
"stories": [
{ "title": "Show HN: …", "score": "312", "item_url": { "$lens": "@djgrant/hn/item", "params": { "id": "41234567" } } }
],
"next_page": { "$lens": "@djgrant/hn/top", "params": { "page": 2 } }
},
"resolver": "dom",
"tab": "t1834"
}value always matches the shape the lens declares, so stories is always an array of objects with a title.
item_url and next_page are follow-up calls. To get page 2, call what next_page names:
lens call @djgrant/hn/top --params '{"page": 2}'outcome: the page is in a known state
The page is in a state the lens author named, usually signed out. From claude/usage:
{
"kind": "outcome",
"name": "needs_auth",
"value": { "$lens": "@djgrant/claude/login" },
"hint": "Ask the user to sign in to claude.ai in the open tab, then retry this call."
}hint is for a person to read. value is a follow-up call that fixes the problem.
In a terminal, lens call waits up to two minutes for you to sign in, then runs the lens again. Outside a terminal it returns the outcome at once. --auth-lease-ms sets the wait; 0 turns it off.
error: the call failed
{
"kind": "error",
"code": "writes_not_allowed",
"message": "@djgrant/chatgpt/send performs writes; call it with allowWrites: true to consent"
}The most common error is a shape mismatch: the page changed, and the data no longer fits the declared shape. The result then lists each mismatch in issues. --lax returns the value anyway, with the mismatches in warnings.
The CLI exits with 1 only for errors. An outcome exits with 0, so a script that checks only the exit status treats "signed out" as success. Read kind instead. The CLI reference lists every error code.
Calling again in the same tab
Pass a result's tab id back to run in the same browser tab:
lens call hn/item --params '{"id": "41234567"}' --tab t1834Use this when a site keeps state in the tab, such as a half-finished form. A closed tab fails with tab_closed.
Cached results
hn/top declares that its results stay fresh for 60 seconds. A second call within a minute returns the first result, marked "cached": true, without loading the page. Only values are cached. --no-cache forces a fresh read.
Lenses that change things
chatgpt/send types a message and presses send. The broker refuses lenses that change things unless you pass --allow-writes:
lens call chatgpt/send --params '{"message": "hello"}' --allow-writesA retry can send the message twice, so check the result first:
"performed": truemeans the write happened. Do not retry.- A timeout error carries a
mutationobject. If itsperformedis"unknown", check the site before you retry.
A lens marked idempotent is safe to retry. lens list shows the flag. Write and File Lenses explains how authors declare writes.
Lenses that return files
Save a statement PDF into an existing directory:
lens call bank/statement-pdf --params '{"id": "123"}' --out-dir ~/Statementsvalue describes the saved file, with its absolute path, name, mimeType and bytes. Without --out-dir, the call fails with out_dir_required.