deepline 0.3.461 → 0.3.463

package/dist/cli/{chunk-R2GLGLDR.mjs → chunk-VPHN2HAL.mjs}

@@ -4,9 +4,8 @@ var CONVENTIONS = `
 Conventions (apply to every command):
   Output mode: readable text by default. Add --json for machine-readable
     output: stdout is one JSON document, including errors and notices;
-    stderr stays empty. tools execute is the exception: it prints JSON;
-    --output-format csv prints a readable summary and writes the rows to a
-    CSV file.
+    stderr stays empty. run is the exception: it saves the data to a file
+    and prints a receipt naming it, as JSON under --json.
   Streams: without --json, stdout carries only the command result. Progress,
     update notices, skills-sync notes, and warnings go to stderr.
   Piping JSON: pass --json only when a program parses the output. Under
@@ -25,7 +24,7 @@ Conventions (apply to every tool):
 ]]
   Ids: play references look like prebuilt/person-to-phone-batch or
     <workspace-slug>/my-play; run ids look like
-    play/<play-ref>/run/<timestamp>-<suffix> and are printed by [[plays run]].
+    play/<play-ref>/run/<timestamp>-<suffix> and are printed by [[cli:run]][[mcp:deepline_run_play]].
 [[cli:
   Large results: prefer the narrower command over post-processing a big
     payload: runs export for rows, billing usage --run-id for cost,
@@ -56,18 +55,18 @@ What Deepline is for:
   phones, research accounts, and keep durable, resumable runs of that work.
   Three nouns cover almost everything:
     tools  one provider or API operation (search, enrich, verify). Atomic,
-           priced per call. Discover with [[search]], inspect with [[tools
-           describe]], call with [[tools execute]].
-    plays  a durable workflow, usually a prebuilt waterfall over a CSV. Discover
-           with [[search]], read the contract with [[cli:describe]][[mcp:deepline_describe_play]], start with
-           [[plays run]].
+           priced per call.
+    plays  a durable workflow, usually a prebuilt waterfall over a CSV.
+    runs   one execution of a play: status, rows, logs, and cost.
 [[cli:
-    runs   one execution of a play: status, rows, logs, cost, and export.
-           Inspect with runs get, download rows with runs export.
+  Find a tool or play with search, read its contract with describe, and run
+  it with run. Read a run again with runs get.
 ]]
 [[mcp:
-    runs   one execution of a play: status, rows, logs, and cost. Inspect
-           with deepline_get_run, read rows with deepline_read_play_output.
+  Find a tool or play with deepline_search, read its contract with
+  deepline_describe_tool or deepline_describe_play, and run it with
+  deepline_execute_tool or deepline_run_play. Read a run with
+  deepline_get_run and its rows with deepline_read_play_output.
 ]]
 
 The agent path for a typical task:
@@ -78,10 +77,10 @@ The agent path for a typical task:
   2. deepline search "<input you have -> result you need>"
                                     one search over prebuilt plays, tools, your
                                     workspace's plays, and monitor types
-  3. deepline describe <ref>  read required input, CSV columns, output
-  4. deepline plays run <ref> --input '{"csv":"file.csv"}'   waits, prints run id
-  5. deepline runs export <run-id> --out result.csv          rows as CSV
-  6. deepline billing usage --run-id <run-id>                what it cost
+  3. deepline describe <id>         required input, CSV columns, output, price
+  4. deepline run <id> --input '{"csv":"file.csv"}' --csv-out result.csv
+                                    waits, saves the rows, prints a receipt
+                                    with the run id and what it cost
 ]]
 [[mcp:
   1. deepline_auth_status     the connected workspace
@@ -93,7 +92,8 @@ The agent path for a typical task:
   5. deepline_read_play_output   the result rows, a page at a time
   6. deepline_billing_usage with run_id   what it cost
 ]]
-  Use [[tools execute]] only when no play covers the job or for one-off lookups.
+  Run a play for work over rows; run a tool for a single lookup or when no
+  play covers the job.
 ${CONVENTIONS}`,
     verbose: `
 Working rules:
@@ -101,25 +101,23 @@ Working rules:
     company domains -> each company's lead investors"]].
     Results are ranked for what you have and what you need, and each one
     names its kind: prebuilt play, tool, custom play, or monitor type.
-  A CSV goes through the batch form of a prebuilt play, never one
+  A CSV goes through the batch form of a prebuilt play, in one run for the
 [[cli:
-    single-record run per row: plays run prebuilt/<play>-batch --input
-    '{"csv":"leads.csv"}', then runs export <run-id> --out <path>. Work
+    whole file: run prebuilt/<play>-batch --input '{"csv":"leads.csv"}'
+    --csv-out <path>. Work
 ]]
 [[mcp:
-    single-record run per row: deepline_run_play with play
-    prebuilt/<play>-batch, the CSV rows in input_file, and inputs
-    {"csv": "<input_file.path>"}. Read the rows with
-    deepline_read_play_output. Work
-]]
-    emails: person-to-email-batch takes the whole file in one run. Each row
-    tries its LinkedIn profile first and falls through to name and company
-    domain, so do not split the file or run a second pass. Phones: a known
-    person -> person-to-phone-batch.
+    whole file: deepline_run_play with play prebuilt/<play>-batch, the CSV
+    rows in input_file, and inputs {"csv": "<input_file.path>"}. Read the
+    rows with deepline_read_play_output. Work
+]]
+    emails: person-to-email-batch. Each row tries its LinkedIn profile first
+    and falls through to name and company domain, so one pass covers the
+    file. Phones: a known person -> person-to-phone-batch.
   The balance is a ceiling, not a budget to use up. Before each paid call,
 [[cli:
-    estimate its cost: the price from describe <tool> or
-    plays list --show-cost, times the results or rows you will request. Take
+    estimate its cost: run <id> --dry-run shows the price, times the results
+    or rows you will request. Take
 ]]
 [[mcp:
     estimate its cost: the price from deepline_describe_tool or
@@ -310,12 +308,18 @@ When:
 Input:
   --run-id <run-id> scopes the spend to one play run. --limit and --cursor
   page the recent-call list. --json prints JSON.
+  --events reads raw usage-event history instead of the spend summary. Combine
+  it with --run-id, --limit (1\u2013500), and --cursor; not --offset or --request-id.
+  Follow next_cursor until null, even when entries is empty.
 ]]
 [[cli:
 Output (JSON):
   balance, usage.last_30_days_usage_credits, usage.month_spent_credits, and
   with --run-id: run.spent_credits, run.rough_usd_spent, run.event_count.
   render.sections includes a "Run spend: N Deepline Credits" line.
+  With --events: org_id, run_id, entries, next_cursor, and next.page. Entries
+  retain original run attribution and nullable recorded Deepline credits;
+  raw event history is not final settlement evidence.
 ]]
 [[mcp:
 Output:
@@ -354,43 +358,32 @@ Cases:
   search: {
     core: `
 Purpose:
-  One ranked search across everything Deepline can run: provider tools,
-  prebuilt plays, plays this workspace created, and monitor types. Each
-  result names its kind.
+  Find the play, tool, or monitor for a task. One search covers all of them.
 When:
-  First, for any task where you do not already know the exact play or tool.
-  Search once with the task; there is no separate search for plays and for
-  tools.
-[[cli:
+  First, whenever you do not already know what to run.
 Input:
-  One argument: the task as a sentence, written as the input you have ->
-  the result you need, for example "50 company domains -> each one's lead
-  investors". Do not send keywords; the sentence is what ranks the results.
-  --type narrows to tools, prebuilts, custom, plays (prebuilts
-  and custom), or monitors, and --exclude leaves kinds out; both take a
-  comma-separated list. --categories <a,b> and --search_terms <a,b> filter
-  tools and work without a task. --limit (1-50) and --offset page.
+  The task as one sentence. For work on data, write what you have -> what
+  you need. Sentences rank better than keywords.
+Examples:
+[[cli:
+  deepline search "first name, last name and company domain -> verified work email"
+  deepline search "50 company domains -> each one's lead investors"
+  deepline search "company domain -> contacts in sales leadership" --type plays
+  deepline search "upload a contact list as a Meta ads audience"
+]]
+[[mcp:
+  query "first name, last name and company domain -> verified work email"
+  query "50 company domains -> each one's lead investors"
+  query "company domain -> contacts in sales leadership"
+  query "upload a contact list as a Meta ads audience"
 ]]
 Output:
-  [[cli:A readable ranked list by default; read that form. With
-  --json: ]]results[] where each item has id, kind (tool, prebuilt_play,
-  custom_play, monitor_type), displayName, and description. A tool adds
-  provider, categories, inputFields, pricing, connected, and executeCommand;
-  a play adds reference, inputFields, describeCommand, and runCommand. Also
-  kinds, count, total, next_offset when there is another page, and
-  render.sections.
+  A ranked list. Each result has an id, its kind, what it does, and its price.
 Cost:
   Free.
 Next:
-  [[cli:describe]][[mcp:deepline_describe_tool or deepline_describe_play]] <id> reads any result, whatever its kind. Then [[plays run]] for a
-  play, [[tools execute]] for a tool. When a play and a tool both fit a job with
-  rows, take the play.
-Avoid:
-  Do not hardcode a provider list; [[search]] returns what this workspace can
-  call now. Do not run anything from search output alone; describe it first.
-[[cli:
-  tools search and plays search are deprecated aliases of this command.
-]]
+  [[cli:describe]][[mcp:deepline_describe_tool or deepline_describe_play]] <id> before running anything, then
+  [[cli:run <id>]][[mcp:deepline_execute_tool or deepline_run_play]] to run it. When both fit, take the play.
 `
   },
   describe: {
@@ -413,7 +406,7 @@ Input:
   A tool lists its features, such as the model an AI tool runs;
   --feature <name>[=<value>] describes one.
   A play your workspace created is shown instead of a Deepline tool or
-  prebuilt play of the same name; --prebuilt shows the Deepline one.
+  prebuilt play of the same name; deepline/<name> shows the Deepline one.
 ]]
 [[cli:
 Output:
@@ -423,6 +416,26 @@ Output:
 ]]
 Cost:
   Free.
+`
+  },
+  run: {
+    core: `
+Purpose:
+  Run a tool, a play or a play file by name, or code inline with -e, with
+  one JSON input. Every kind answers with the same receipt.
+When:
+  After describe, once you know the inputs. --dry-run checks the input and
+  the price first. -e runs a few lines that call tools without writing a
+  play file.
+Output:
+  The data in a file, and a receipt with what ran, its cost, and the values
+  that came back. --json prints the receipt as JSON.
+Next:
+  Read the data file the receipt names. deepline runs get <id> reads the
+  run or tool call again.
+Cost:
+  Spends credits as the tool or play does. Running an interrupted call again
+  replays it at no extra cost.
 `
   },
   tools: {
@@ -432,15 +445,15 @@ Purpose:
   company, verify an email), priced per call in Deepline credits.
 When:
   For one-off lookups, candidate searches, or when search finds no play
-  for the job. For CSV-shaped work use a play instead: plays retry,
-  reuse completed rows, and export.
+  for the job. CSV-shaped work goes through a play, which retries, reuses
+  completed rows, and exports.
 The sequence:
   [[search <words>]]              ranked tools and plays for an intent
   [[cli:describe <id>]][[mcp:deepline_describe_tool]]         required input fields, pricing, output shape
-  [[tools execute <id> --input '{...}']]   run it
+  [[cli:run <id> --input '{...}']][[mcp:deepline_execute_tool]]    run it
 Cost:
-  search, describe, list, and grep are free. execute can spend credits; the
-  price is in [[cli:describe <id>]][[mcp:deepline_describe_tool]].
+  search, describe, list, and grep are free. Running a tool can spend
+  credits; [[cli:run <id> --dry-run]][[mcp:deepline_describe_tool]] shows the price.
 `
   },
   "tools connect": {
@@ -449,6 +462,10 @@ Purpose:
   Connect a provider to the active workspace. Requires an owner or admin.
 Input:
   --credentials-file <path> saves a private JSON object of credential strings.
+  A provider that takes one API key reads {"api_key": "..."}; a file with one
+  field is accepted whatever the field is named. A multi-field provider (for
+  example a warehouse) rejects a missing field and lists its accepted field
+  names in the error.
   --oauth prints an authorization URL. Open it in a browser signed into the
   same Deepline workspace and finish provider consent.
   HubSpot: --preset read-crm, update-crm, marketing, sales-sequences, tickets, or all.
@@ -463,7 +480,8 @@ Output:
   completed connection. The browser must finish authorization.
 Cost:
   Does not spend Deepline credits.
-Example:
+Examples:
+  deepline tools connect heyreach --credentials-file ./heyreach.json
   deepline tools connect hubspot --oauth --preset read-crm
 `
   },
@@ -576,12 +594,11 @@ Output fields:
                          connect them. With byok optional and nothing
                          connected, Deepline's managed credentials are used.
   extractors / targetGetters  JSON paths the CLI uses to turn the raw provider
-                         response into rows; the same paths appear in tools
-                         execute output as output_preview.listSourcePath.
+                         response into rows.
   usageGuidance          provider-specific notes worth reading once.
 ]]
 Related:
-  [[tools execute <id>]][[cli: --input @file.json]] uses the same schema; runtime output
+  [[cli:run <id> --input-file input.json]][[mcp:deepline_execute_tool]] takes the same schema; runtime output
   help for authoring a play appears under runtimeOutputHelp.
 `
   },
@@ -672,18 +689,17 @@ When:
 [[cli:
 The sequence:
   search "<input you have -> result you need>"   find the play
-  describe <ref>          required input, CSV columns, output fields
+  describe <ref>                required input, CSV columns, output fields
   plays list --show-cost        per-row or per-run credit estimate
-  plays run <ref> --input '{"csv":"file.csv"}'   start and wait
-  runs export <run-id> --out out.csv             rows
+  run <ref> --input '{"csv":"file.csv"}' --csv-out out.csv   run it, save rows
 Writing a play:
   Start from code that already works, not a blank file.
   plays get prebuilt/<name> --source --out my.play.ts
                                 copy the closest prebuilt and edit the copy
   plays check my.play.ts        validate after every edit; free
-  plays run my.play.ts --input '{...}'           run the local file
-  plays publish my.play.ts      make it live for plays run <name> and triggers
-  plays run -e "<code>"         run code inline as a play function's body
+  run my.play.ts --input '{...}'                 run the local file
+  plays publish my.play.ts      make it live for run <name> and triggers
+  run -e "<code>"               run code inline as a play function's body
                                 (input holds --input), like python -c
   A play is a default-exported async function of its input; the file name
   is its default name:
@@ -868,7 +884,8 @@ Pricing a run:
 [[cli:
 Output fields:
   costEstimate.source      "observed" (from past runs; shown with ~) or
-                           "static" (from the play's declared tools).
+                           "static" (a hand-written range or the play's
+                           declared tools).
   costEstimate.sampleRunCount  how many runs the observation is based on.
   observedCost             avgCredits, medianCredits, maxCredits per unit across
                            all workspaces' runs, or status "unavailable" with
@@ -1144,13 +1161,13 @@ Cost:
   "plays set-live": {
     core: `
 Purpose:
-  Make one version of a play live, so [[plays run <name>]], triggers, and
+  Make one version of a play live, so [[cli:run <name>]][[mcp:deepline_run_play]], triggers, and
   deepline.runPlay callers use it.[[cli: A local .play.ts file is bundled, validated,
   saved as a revision, and promoted in one step; a saved play promotes one
   of its existing revisions.]][[mcp: It promotes one of a saved play's existing
   revisions; deepline_publish_play saves and promotes a new file graph.]]
 When:
-  After iterating on [[cli:a local file with plays run ./file.play.ts]][[mcp:a play with deepline_run_inline_play]], once its
+  After iterating on [[cli:a local file with run ./file.play.ts]][[mcp:a play with deepline_run_inline_play]], once its
   result is right. Running [[cli:a local file]][[mcp:a play inline]] never publishes it.
 [[cli:
 Input:
@@ -1175,8 +1192,8 @@ Avoid:
   "plays publish": {
     core: `
 Purpose:
-  Publish [[cli:a local .play.ts file]][[mcp:an inline .play.ts file graph]] or promote a saved revision, so [[plays run
-  <name>]], triggers, and deepline.runPlay callers use it. The same operation as
+  Publish [[cli:a local .play.ts file]][[mcp:an inline .play.ts file graph]] or promote a saved revision, so [[cli:run
+  <name>]][[mcp:deepline_run_play]], triggers, and deepline.runPlay callers use it. The same operation as
   [[plays set-live]].
 When:
   Once a play [[cli:run by file path]][[mcp:run inline]] gives the right result. Running [[cli:a local file]][[mcp:a play inline]]
@@ -1225,7 +1242,7 @@ Which command:
                                 active run
 ]]
 Ids:
-  play/<play-ref>/run/<timestamp>-<suffix>, printed by [[plays run]] as runId.
+  play/<play-ref>/run/<timestamp>-<suffix>, printed in [[cli:run's receipt as Id]][[mcp:deepline_run_play's result as runId]].
 Cost:
   All of these are free; a run's spend was charged while it ran.
 `
@@ -1332,6 +1349,9 @@ Input:
   returned more than one (default: the returned dataset, usually
   result.rows). --metadata-out <path.json> writes the export metadata. --json
   prints the receipt as JSON; it does not change the file format.
+  --summary counts keeps exact row counts while skipping column aggregates
+  during retrieval; every saved row and column is still exported. The default
+  --summary full includes column aggregates.
   To parse the receipt, add --json; stdout is then one JSON document.
 ]]
 Output (JSON):
@@ -1388,9 +1408,9 @@ Cost:
 Avoid:
   runs[].id is the public run id that [[runs get]], watch, export and stop
   accept. runId and workflowId are older names for it; temporalRunId is a
-  backend identifier and not a run id. Use the id [[plays run]] returned for
-  your own run: the latest entry here may belong to another invocation that
-  started at the same time.
+  backend identifier and not a run id. Use the id your own run returned:
+  the latest entry here may belong to another invocation that started at the
+  same time.
 `
   },
   "runs logs": {
@@ -1468,8 +1488,8 @@ Avoid:
 Purpose:
   Follow an active run until it ends, polling its status every two seconds.
 When:
-  Only for a run started with --no-wait that you want to watch. plays run
-  already waits, and runs get answers "is it done". runs tail is an alias.
+  For a run started with run --timeout 0, or one run stopped waiting for.
+  runs get answers "is it done". runs tail is an alias.
 [[cli:
 Input:
   The run id. --compact shows step transitions only; --json prints one
@@ -1531,7 +1551,7 @@ Input:
   The run id. --json.
 ]]
 Output (JSON):
-  The new run's package, as [[plays run]] prints.
+  The new run's package, as plays run --json prints.
 Cost:
   Spends credits only for rows that were not completed before.
 `
@@ -1572,7 +1592,7 @@ Purpose:
   Inspect a local CSV before running a play over it: headers, fill rates,
   sample values, or a row range.
 When:
-  Before [[plays run]], to confirm the file has the columns describe requires
+  Before [[cli:run]][[mcp:deepline_run_play]], to confirm the file has the columns describe requires
   and to count rows for pricing. Free and local.
 [[cli:
 Input:
@@ -1615,6 +1635,111 @@ Cost:
 Avoid:
   Do not guess table names; a run's dataset table is named in [[runs get]]
   under datasets[].storage.
+`
+  },
+  pages: {
+    rolloutFeature: "hosted-pages",
+    core: `
+Purpose:
+  Publish a document at a stable URL on your workspace's subdomain of
+  deepline.page, and decide who can open it. A page is one named document:
+  HTML, JSON, CSV, Markdown, text, SVG, an image, or a PDF, up to 3 MB.
+When:
+  To share a report, dashboard, or result with people, from a terminal or at
+  the end of a Play. Writing the same name again replaces the page and keeps
+  its URL, so a Play that runs daily can keep one page current.
+The sequence:
+  1. Write it. From a terminal: [[pages write <name> --file report.html
+     --private]]. From a Play: ctx.pages.write(name, { public: false,
+     content }). The URL, https://<label>.deepline.page/p/<name>, is in the
+     output and stays the same for every write.
+  2. Choose who can open it. Every write must say private or public:
+     private  Workspace members, after signing in to Deepline.
+     link     Anyone holding a URL from [[pages links create <name>]]. A link
+              opens one page, shows its current content, and expires
+              (--expires-in 7d) or lasts until revoked (--permanent).
+     public   Anyone with the URL. Needs public pages enabled for the
+              workspace; [[pages list]] says whether they are. A private page
+              becomes public only through [[pages set-public <name>]], never
+              through a write.
+  3. Manage it: [[pages list]], [[pages get <name>]],
+     [[pages set-private <name>]], [[pages links list <name>]],
+     [[pages links revoke <name> <link-id>]], [[pages delete <name>]]. The
+     Pages section of the dashboard has the same actions.
+What visitors see:
+  HTML, SVG, and XML open in a sandbox under a "Hosted on Deepline" tab.
+  Scripts, forms, and https requests work. A link to another site asks the
+  visitor before it opens. Other types, and requests from curl or code, get
+  the bytes exactly as written.
+Cost:
+  Free. Each new page counts toward the plan's page limit, which
+  [[pages list]] prints; replacing a page does not.
+Avoid:
+  Do not put secrets or credentials in a page, even a private one: anyone with
+  a link sees everything on it. Do not write a new name per run to keep
+  history; use one name so the URL stays stable.
+`
+  },
+  "pages write": {
+    rolloutFeature: "hosted-pages",
+    core: `
+Purpose:
+  Create a page, or replace all of its content and its description.
+[[cli:
+Input:
+  <name>: 1-63 lowercase letters, digits, or hyphens, starting and ending
+  with a letter or digit. --file <path> (required, up to 3 MB). Exactly one
+  of --private or --public. --content-type <type> overrides the type taken
+  from the extension (.html .htm .json .csv .md .txt .svg .png .jpg .jpeg
+  .gif .webp .pdf; anything else is application/octet-stream).
+  --description <text>. --json prints JSON.
+]]
+Output (JSON):
+  name, url, public (who can open it after this write), revision (increases
+  only when the content changes), created (true for a new page), and
+  warnings[] (for example, a request for public that kept a page private).
+Visibility:
+  --private makes a public page private at once. --public publishes a new
+  page. On a page that is already private, --public writes the content, keeps
+  the page private, and adds a warning; run [[pages set-public <name>]] to
+  publish it. Without public pages enabled, --public fails with
+  public_pages_not_enabled and writes nothing.
+Errors (code):
+  name_invalid, content_type_invalid, description_too_long,
+  document_too_large, page_limit_reached, page_deleting,
+  public_pages_not_enabled, pages_not_enabled.
+Cost:
+  Free. Repeating a write is safe.
+Avoid:
+  Do not use --public for something only your team should see. Write it
+  --private and share it with [[pages links create <name>]].
+`
+  },
+  "pages links create": {
+    rolloutFeature: "hosted-pages",
+    core: `
+Purpose:
+  Create a URL that opens one page without signing in.
+When:
+  To share a private page with someone outside the workspace, or for a limited
+  time. Works without public pages enabled.
+[[cli:
+Input:
+  <name>, then exactly one of --expires-in <duration> (30m, 12h, 7d) or
+  --permanent. --label <text> says who the link is for. --json prints JSON.
+]]
+Output (JSON):
+  url (printed once and never again; Deepline keeps only a hash), id (pass it
+  to [[pages links revoke <name> <link-id>]]), label, expires_at (null when
+  permanent), created_at.
+Behavior:
+  The link always shows the page's current content, keeps working after
+  writes, and stops at once when revoked or when the page is deleted. A page
+  can have up to 100 links; [[pages links list <name>]] lists them.
+Cost:
+  Free.
+Avoid:
+  Do not post a link anywhere public: it opens the page for anyone holding it.
 `
   },
   "sessions send": {