@audienti/cli 0.1.145 → 0.2.0-exora.10

package/cli/assignment.mjs

@@ -0,0 +1,116 @@
+import { callWorkspace, configuration } from "./workspaces.mjs";
+import { readJsonFile } from "./json-file.mjs";
+export function isAssignmentCommand(args) {
+  return (
+    args[0] === "workspace" &&
+    (["assignments", "prospect", "routing-rules", "routing", "leave"].includes(
+      args[1],
+    ) ||
+      (args[1] === "member" && args[2] === "remove"))
+  );
+}
+export async function assignmentCli(args) {
+  const flags = {},
+    position = [];
+  const children = [
+    "history",
+    "participations",
+    "participation-events",
+    "routing-reports",
+    "overrides",
+  ];
+  const allowed = [
+    "profile",
+    "workspace",
+    "file",
+    "request-id",
+    "prospect-id",
+    "campaign-id",
+    "assigned-to-user-id",
+    "unassigned",
+    "search",
+    "cursor",
+    "limit",
+    ...children.flatMap((k) => [k + "-cursor", k + "-limit"]),
+  ];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--json") continue;
+    if (!args[i].startsWith("--")) {
+      position.push(args[i]);
+      continue;
+    }
+    const key = args[i].slice(2);
+    if (
+      !allowed.includes(key) ||
+      args[i + 1] === undefined ||
+      args[i + 1].startsWith("--") ||
+      Object.hasOwn(flags, key)
+    )
+      throw new Error("Unknown, repeated, or incomplete assignment option.");
+    flags[key] = args[++i];
+  }
+  const command = position.join(" ");
+  const names = {
+    "workspace assignments list": "workspace_prospect_assignments",
+    "workspace prospect assignment get": "workspace_prospect_assignment",
+    "workspace prospect assignment set": "workspace_prospect_assignment_set",
+    "workspace prospect campaign-fit get":
+      "workspace_prospect_campaign_fit",
+    "workspace routing-rules get": "workspace_routing_rules_get",
+    "workspace routing-rules replace": "workspace_routing_rules_replace",
+    "workspace routing apply": "workspace_routing_apply",
+    "workspace prospect fit-override set": "workspace_fit_override_set",
+    "workspace prospect fit-override clear": "workspace_fit_override_set",
+    "workspace prospect move": "workspace_prospect_move",
+    "workspace member remove": "workspace_member_remove",
+    "workspace leave": "workspace_leave",
+  };
+  const name = names[command];
+  if (!name)
+    throw new Error(
+      "Unknown assignment command. Use workspace assignments list, prospect assignment get/set, routing-rules get/replace, routing apply, prospect campaign-fit get, prospect fit-override set/clear, prospect move, member remove, or leave. Mutations require --file INPUT.json.",
+    );
+  const read = [
+    "workspace_prospect_assignments",
+    "workspace_prospect_assignment",
+    "workspace_prospect_campaign_fit",
+    "workspace_routing_rules_get",
+  ].includes(name);
+  let input = read ? {} : readJsonFile(flags.file, 65536, "Assignment file");
+  for (const [flag, key] of [
+    ["workspace", "workspaceId"],
+    ["request-id", "requestId"],
+    ["prospect-id", "prospectId"],
+    ["campaign-id", "campaignId"],
+    ["assigned-to-user-id", "assignedToUserId"],
+    ["search", "search"],
+    ["cursor", "cursor"],
+  ])
+    if (flags[flag] !== undefined) input[key] = flags[flag];
+  if (flags.limit !== undefined) input.limit = Number(flags.limit);
+  if (flags.unassigned !== undefined) {
+    if (!["true", "false"].includes(flags.unassigned))
+      throw new Error("--unassigned must be true or false.");
+    input.unassigned = flags.unassigned === "true";
+  }
+  for (const child of children) {
+    const cursor = flags[child + "-cursor"],
+      limit = flags[child + "-limit"];
+    if (cursor !== undefined || limit !== undefined)
+      input[child.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = {
+        ...(cursor === undefined ? {} : { cursor }),
+        ...(limit === undefined ? {} : { limit: Number(limit) }),
+      };
+  }
+  if (name === "workspace_fit_override_set") {
+    const action = position.at(-1);
+    if (input.action !== undefined && input.action !== action)
+      throw new Error("File action must match the command.");
+    input.action = action;
+  }
+  console.log(
+    JSON.stringify(
+      await callWorkspace(name, input, configuration(flags.profile)),
+    ),
+  );
+}

package/cli/attachment-operations.mjs

@@ -0,0 +1,9 @@
+import {z} from 'zod';
+// #413: a file is uploaded first and named by id in a LinkedIn message (content.attachments). An image is at most 5 MB;
+// a voice note is at most 2 minutes and 5 MB.
+const uuid=z.string().uuid(),maxBytes=5*1024*1024;
+const base64=z.string().min(4).max(4*Math.ceil(maxBytes/3)+8).refine(value=>value.length%4===0&&/^[A-Za-z0-9+/]+={0,2}$/.test(value));
+export const attachmentOperations={
+ attachment_upload:{schema:z.object({workspaceId:uuid.optional(),name:z.string().trim().min(1).max(255),contentType:z.string().max(127),contentBase64:base64,durationSeconds:z.number().int().positive().max(120).optional()}).strict(),method:'POST',path:a=>`${a.workspaceId?`/workspaces/${a.workspaceId}`:''}/attachments`,body:a=>({name:a.name,contentType:a.contentType,contentBase64:a.contentBase64,...(a.durationSeconds?{durationSeconds:a.durationSeconds}:{})}),scoped:true,description:'Store an image (jpeg, png, gif, webp; at most 5 MB) or a voice note (mpeg, mp4, ogg, wav, webm; at most 5 MB and 2 minutes) and return its id. Name the id in content.attachments of a linkedin.send action tagged profile.message.send. A voice note needs durationSeconds and goes only to a connection. Needs workspace:access.'},
+ attachment_get:{schema:z.object({workspaceId:uuid.optional(),attachmentId:uuid}).strict(),method:'GET',path:a=>`${a.workspaceId?`/workspaces/${a.workspaceId}`:''}/attachments/${a.attachmentId}`,scoped:true,description:'One uploaded file with its content as base64. An agent that sends from its own LinkedIn account fetches the file here, then attaches it in LinkedIn.'},
+};

package/cli/attachments.mjs

@@ -0,0 +1,28 @@
+import {readFileSync,writeFileSync,statSync} from 'node:fs';
+import {basename,extname} from 'node:path';
+import {callWorkspace,configuration} from './workspaces.mjs';
+const help='Use attachments upload FILE [--type MIME] [--name NAME] [--duration SECONDS] [--workspace ID] [--profile PATH], or attachments get ATTACHMENT_ID --out PATH [--workspace ID] [--profile PATH]. An image is at most 5 MB; a voice note is at most 2 minutes and 5 MB, and its length goes in --duration.';
+const TYPES={'.jpg':'image/jpeg','.jpeg':'image/jpeg','.png':'image/png','.gif':'image/gif','.webp':'image/webp','.mp3':'audio/mpeg','.m4a':'audio/mp4','.ogg':'audio/ogg','.wav':'audio/wav'};
+export async function attachmentsCli(args){
+ const position=[],flags={};for(let i=1;i<args.length;i++){
+  if(!args[i].startsWith('--')){position.push(args[i]);continue}
+  const key=args[i].slice(2);if(key==='json')continue;if(!['profile','workspace','type','name','duration','out'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error(`Unknown or incomplete attachments option. ${help}`);
+  flags[key]=args[++i];
+ }
+ const config=configuration(flags.profile);
+ if(position[0]==='upload'&&position.length===2){
+  const file=position[1],type=flags.type??TYPES[extname(file).toLowerCase()];
+  if(!type)throw new Error(`Give --type for this file. ${help}`);
+  const stat=statSync(file);if(!stat.isFile()||stat.size>5*1024*1024)throw new Error('The file must be a regular file of at most 5 MB.');
+  const duration=flags.duration===undefined?undefined:Number(flags.duration);
+  if(duration!==undefined&&!Number.isInteger(duration))throw new Error('--duration is a whole number of seconds.');
+  const result=await callWorkspace('attachment_upload',{workspaceId:flags.workspace,name:flags.name??basename(file),contentType:type,contentBase64:readFileSync(file).toString('base64'),...(duration===undefined?{}:{durationSeconds:duration})},config);
+  console.log(JSON.stringify(result.data));return;
+ }
+ if(position[0]==='get'&&position.length===2&&flags.out){
+  const result=await callWorkspace('attachment_get',{workspaceId:flags.workspace,attachmentId:position[1]},config);
+  const {contentBase64,...rest}=result.data;writeFileSync(flags.out,Buffer.from(contentBase64,'base64'));
+  console.log(JSON.stringify({...rest,savedTo:flags.out}));return;
+ }
+ throw new Error(help);
+}

package/cli/audience-operations.mjs

@@ -0,0 +1,21 @@
+import {z} from 'zod';
+const uuid=z.string().uuid(),workspace={workspaceId:uuid.optional()},locator={...workspace,audienceId:uuid};
+const criterion=z.object({name:z.string(),providerId:z.string().nullable().optional(),negative:z.boolean().optional()}).strict();
+const location=criterion.extend({key:z.string().nullable().optional()}).strict();
+const strings=z.array(z.string()).optional(),criteria=z.array(criterion).optional(),locations=z.array(location).optional();
+const fields=z.object({name:z.string(),tags:strings,textCriteria:z.string().optional(),notes:z.string().optional(),discoveryKeyword:z.string().optional(),seniorityMatchMode:z.enum(['at_least','exact']).optional(),company:z.object({industries:criteria,industryGroups:strings,sizes:criteria,types:criteria,locations,keywords:z.object({include:strings,exclude:strings}).strict().optional()}).strict(),person:z.object({locations,currentTitles:criteria,pastTitles:criteria,seniorities:criteria,functions:criteria,bioPhrases:z.array(z.object({phrase:z.string(),negative:z.boolean().optional()}).strict()).optional(),allowedTitleExceptions:strings}).strict()}).strict();
+const path=a=>`/workspaces/${a.workspaceId}/audiences`;
+export const audienceOperations={
+ audience_options:{schema:z.object({...workspace,kind:z.enum(['industries','industry_groups','sizes','types','seniorities','titles','locations','functions']),q:z.string().max(200).optional()}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/audience-options?`+new URLSearchParams({kind:a.kind,...(a.q!==undefined?{q:a.q}:{})}),scoped:true},
+ audience_list:{schema:z.object({...workspace,archived:z.boolean().optional(),limit:z.number().int().optional(),after:uuid.optional(),q:z.string().optional()}).strict(),method:'GET',path:a=>path(a)+'?'+new URLSearchParams(Object.fromEntries(Object.entries({archived:a.archived,limit:a.limit,after:a.after,q:a.q}).filter(([,v])=>v!==undefined).map(([k,v])=>[k,String(v)]))),scoped:true},
+ audience_get:{schema:z.object({...locator,revision:z.number().int().optional()}).strict(),method:'GET',path:a=>path(a)+`/${a.audienceId}`+(a.revision===undefined?'':`?revision=${a.revision}`),scoped:true},
+ audience_create:{schema:z.object({...workspace,requestId:uuid,fields}).strict(),method:'POST',path,body:a=>({requestId:a.requestId,fields:a.fields}),scoped:true},
+ audience_update:{schema:z.object({...locator,expectedRevision:z.number().int(),fields}).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/revisions`,body:a=>({expectedRevision:a.expectedRevision,fields:a.fields}),scoped:true},
+ audience_archive:{schema:z.object(locator).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/archive`,scoped:true},
+ audience_restore:{schema:z.object(locator).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/restore`,scoped:true},
+ audience_summary:{schema:z.object({...workspace,audienceId:uuid.optional()}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/audience-summary`+(a.audienceId?`?audienceId=${a.audienceId}`:''),scoped:true,description:'Counts of active and archived Audiences, the campaigns using each (with people, engaged and at-goal counts), and people found per Audience (recent means admitted in the last 7 days). With audienceId, sizes gives that Audience\'s approximate reachable size against the 1,000-person minimum (null when it cannot be estimated; sizePending while the estimate runs).'},
+ audience_people:{schema:z.object(locator).strict(),method:'GET',path:a=>path(a)+`/${a.audienceId}/people`,scoped:true,description:'People found by any campaign on this Audience, newest first, at most 100, with their latest participation.'},
+ audience_companies:{schema:z.object(locator).strict(),method:'GET',path:a=>path(a)+`/${a.audienceId}/companies`,scoped:true,description:'Companies where this Audience has found people, most people first, at most 100; withoutCompany counts people with no company.'},
+ audience_fit_check_improve:{schema:z.object({...workspace,text:z.string().trim().min(1).max(5000)}).strict(),method:'POST',path:a=>`/workspaces/${a.workspaceId}/audience-fit-checks`,body:a=>({text:a.text}),scoped:true,description:'Review a smart rule (gut check) and suggest a clearer rewrite a reviewer can judge from a profile. Returns whether it is usable, what counts as a match and a contradiction, and the rewrite. Saves nothing.'},
+ audience_prospect_test:{schema:z.object({...locator,url:z.string(),requestId:uuid,revision:z.number().int().positive().optional()}).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/prospect-tests`,body:a=>({url:a.url,requestId:a.requestId,...(a.revision?{revision:a.revision}:{})}),scoped:true,description:'Check one LinkedIn person URL against the Audience rules and name the deciding rule. Read-only: never admits the person. Saved profiles are reused free; otherwise the person and company fetches spend hosted credits. Generate requestId once and reuse it after an interruption so a retry never pays twice.'},
+};

package/cli/audiences.mjs

@@ -0,0 +1,29 @@
+import {callWorkspace,configuration} from './workspaces.mjs';
+import {readJsonFile} from './json-file.mjs';
+export async function audienceCli(args){
+ const position=[],flags={};for(let i=0;i<args.length;i++){
+  if(!args[i].startsWith('--')){position.push(args[i]);continue}
+  const key=args[i].slice(2);if(!['profile','workspace','file','request-id','expected-revision','revision','archived','limit','after','q','kind','url','audience','text'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error('Unknown or incomplete audience option.');
+  flags[key]=args[++i];
+ }
+ const command=position[1],name={options:'audience_options',list:'audience_list',show:'audience_get',create:'audience_create',update:'audience_update',archive:'audience_archive',restore:'audience_restore',summary:'audience_summary',people:'audience_people',companies:'audience_companies',test:'audience_prospect_test',improve:'audience_fit_check_improve'}[command];
+ if(!name||position.length!==(['list','create','options','summary','improve'].includes(command)?2:3))throw new Error('Use audience options --kind KIND [--q TEXT]|list|show ID|create|update ID|archive ID|restore ID|summary|people ID|companies ID|test ID --url URL --request-id UUID [--revision N]|improve --text RULE.');
+ const input={workspaceId:flags.workspace};
+ if(position[2])input.audienceId=position[2];
+ if(command==='options'){input.kind=flags.kind;if(flags.q!==undefined)input.q=flags.q;}
+ if(command==='list'){
+  if(flags.archived!==undefined&&!['true','false'].includes(flags.archived))throw new Error('Archived must be true or false.');
+  if(flags.archived!==undefined)input.archived=flags.archived==='true';
+  if(flags.limit!==undefined)input.limit=Number(flags.limit);
+  if(flags.after)input.after=flags.after;
+  if(flags.q!==undefined)input.q=flags.q;
+ }
+ if(command==='summary'&&flags.audience!==undefined)input.audienceId=flags.audience;
+ if(command==='test'){if(!flags.url)throw new Error('Supply --url with a LinkedIn profile URL.');input.url=flags.url;input.requestId=flags['request-id'];}
+ if(command==='improve'){if(!flags.text)throw new Error('Supply the smart rule with --text.');input.text=flags.text;}
+ if(['show','test'].includes(command)&&flags.revision!==undefined)input.revision=Number(flags.revision);
+ if(['create','update'].includes(command)){if(!flags.file)throw new Error('Supply --file PATH containing Audience fields.');input.fields=readJsonFile(flags.file,65536,'Audience file');}
+ if(command==='create')input.requestId=flags['request-id'];
+ if(command==='update')input.expectedRevision=Number(flags['expected-revision']);
+ console.log(JSON.stringify(await callWorkspace(name,input,configuration(flags.profile))));
+}

package/cli/audienti.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import { isAssignmentCommand, assignmentCli } from './assignment.mjs';
+import { playbookHelp } from './playbook-help.mjs';
+// The CLI is an HTTP client. It has no database access or separate business rules.
+const args = process.argv.slice(2);
+const usage = `Profiles: audienti profiles list|search|get ID | match evaluate|apply SOURCE CANDIDATE | history RESOLUTION (saved workspace records)
+Skills: audienti skills list [--compact]|show SKILL|read SKILL RESOURCE|helper NAME --file INPUT.json|- [--json]
+Tools: audienti call TOOL ['JSON'] | tools search "WORDS"|get TOOL|list|runs|balance [--help]
+Sender: audienti sender accounts list|get|alias|register|bind|unbind|state|automation|activity report [--profile PATH]
+Managed LinkedIn: audienti sender managed list|connect [--workspace ID] [--profile PATH] (connect: the user only; returns a sign-in link)
+                  audienti sender managed plan MANAGED_ACCOUNT_ID --plan free|premium_career|premium_business|premium_all_in_one|sales_navigator_core|sales_navigator_advanced|recruiter_lite|none [--workspace ID]  (the user only; sets the connection note length; none clears it)
+Prospecting: audienti prospecting settings show|save|accounts|account-show|account-save|history [--profile PATH]
+Usage: audienti whoami [--json]
+       audienti workspace assignments list [--workspace ID]
+       audienti workspace prospect assignment get/set --prospect-id ID [--file INPUT.json]
+       audienti workspace routing-rules get/replace [--file INPUT.json]
+       audienti workspace routing apply --file INPUT.json
+       audienti workspace prospect campaign-fit get --prospect-id ID --campaign-id ID
+       audienti workspace prospect fit-override set/clear --file INPUT.json
+       audienti workspace prospect move --file INPUT.json
+       audienti workspace member remove --file INPUT.json
+       audienti workspace leave --file INPUT.json
+
+Required environment:
+  AUDIENTI_API_URL    Backend base URL including /api/v1
+  AUDIENTI_API_TOKEN  Account API token (create it from your Account page)
+
+Use HTTPS for remote hosts. Local HTTP is supported on loopback only.
+Agent commands: agent connect --name NAME [--write (ask for Allow workspace changes up front)] [--capabilities find,enrich,expand,research,engage,sync,notify,approve]|poll|cancel|list|revoke ID --profile PATH
+Owner permission change: agent permission ID --scope workspace:read|workspace:access --profile USER_PROFILE
+Owner capability change: agent capabilities ID --set find,enrich,expand,research,engage,sync,notify,approve --profile USER_PROFILE (agents are refused outside this set)
+Agent capabilities: agent capabilities report --file CAPABILITIES.json --profile AGENT_PROFILE (capability rows; the old per-account shape still works)
+What the agent can do: agent capabilities [--workspace ID] [--json] --profile AGENT_PROFILE (works now, and works with Audienti tools)
+Read capabilities: agent capabilities show [--id AGENT_ID] --profile PROFILE
+Getting started: skills show getting-started, then agent capabilities report --file CAPABILITIES.json --profile AGENT_PROFILE
+Read tool inventory: agent inventory show [--id AGENT_ID] --profile PROFILE (agent inventory report still works; capabilities report is current)
+Account authorization: agent accounts show [--id AGENT_ID] --profile PROFILE
+Authorize/revoke: agent accounts authorize --id AGENT_ID --provider email|linkedin --account REF --authorized true|false --profile OWNER_PROFILE
+Sharing: agent capabilities sharing --id AGENT_ID --profile OWNER_PROFILE
+Share/unshare: agent capabilities share --id AGENT_ID --provider email|linkedin --account REF --workspace ID --shared true|false --profile OWNER_PROFILE
+Team member: workspace member USER_ID [--workspace ID] --profile PROFILE
+Work execution: work execution claim|start|send|get PLAN --action ID (send: managed LinkedIn accounts, --file with claimId and requestId); release|lookup --claim ID; report --attempt ID
+Work feedback: work changes request|list|get|respond|withdraw PLAN --workspace ID
+Work: work plan save|list|show|approve|withdraw-approval|cancel|skip|eligibility
+Activity: work activity --workspace ID [--search TEXT] [--cursor-at ISO --cursor-id ID]
+Work list: work list --workspace ID [--order oldest|priority] [--queue review|blocked|activity]
+           a plan that only waits for its cadence is in neither review nor blocked; it returns to review when the wait ends
+Work writes: --file INPUT.json; human review needs a human workspace:access token
+Audiences: audience options --kind industries|locations|sizes|types|seniorities|titles|functions [--q TEXT]
+           audience list|show ID|create|update ID|archive ID|restore ID
+           audience summary [--audience ID]|people ID|companies ID
+           audience test ID --url LINKEDIN_URL --request-id UUID  (spends hosted credits unless the profile is saved)
+Files: file upload PATH --type MIME|list|prepare|register|download|delete ID (personal files, human token only)
+Queue: audienti queue [list]|next|claim ID [--note TEXT]|done ID [--note TEXT]|skip ID --note TEXT|release ID [--workspace ID]  (start here after you connect; without --workspace an agent reads every workspace its user approved it in; done or skip again with a new --note corrects the note of a finished task)
+Attachments: audienti attachments upload FILE [--duration SECONDS]  (store an image or voice note, get its id for content.attachments)
+Outcome checks: audienti outcomes report TASK_ID --file RESULTS.json  (results for the people an outcomes.check task lists)
+Questions: audienti ask "QUESTION" [--context TEXT] [--option TEXT]... [--campaign ID] [--task ID]  (questions for your user go to Operator, not chat)
+           audienti questions [list] [--state open|answered|withdrawn|all] | show ID | withdraw ID | answer ID --answer TEXT
+Rooms: audienti rooms directory|inbox|ack|send|thread|threads|create|list|read|retire|restore|redact|resume|pause|profile|hook|watch|wait (audienti rooms help)
+KV: audienti kv get KEY|set KEY VALUE [--json] [--nx] [--if-version N] [--ttl 7d|--expires-at TIME]|list [--prefix P]|search [--key TEXT] [--value TEXT]|delete KEY  (small state between runs; never credentials)
+Offers: offer list|show ID|create|update ID|archive ID|restore ID
+Offer options: --file FIELDS.json --request-id UUID --expected-revision N --revision N --archived true|false
+  audienti prospects replies set|get|list PERSON --workspace ID [--evidence EVIDENCE] [--file INPUT.json]
+Account intake: prospects intake --workspace ID --file INPUT.json
+                prospects conversation append|list PERSON --workspace ID
+Discovery: prospects list|get ID|timeline ID [--limit N]|observation create|citation create|evidence create
+           prospects contacts list|record PERSON [--file INPUT.json] [--request-id UUID] --workspace ID
+           prospects contacts get|retire PERSON CONTACT --workspace ID
+           prospects suppression get|set ID --workspace ID
+           guardrails show|pause|resume --workspace ID
+           dnc list|add VALUE|remove VALUE --workspace ID
+           dnc import --file LIST.csv --workspace ID  (at most 5,000 rows; reports added, skipped and invalid rows)
+           dnc export [--output FILE.csv] --workspace ID
+           secret list [--workspace ID]  (names only)
+           secret get NAME [--workspace ID] [--json]  (prints the value; the secret records who read it last and when)
+           budgets show --workspace ID
+           budgets alerts --workspace ID [--limit N]
+           usage breakdown [--workspace ID] [--since month|7d|30d|90d] [--by tool|provider|model|caller|day] [--format json|csv]
+           workspace usage summary|callers|calls [--after ID] [--caller user:ID|agent:ID|key:ID] [--status all|succeeded|failed|pending]|call ID [--workspace ID]  (paid tool use, last 30 days, and single calls)
+           audit list [--workspace ID] [--since 7d] [--actor agent|person] [--category NAME] [--format json|csv]
+           budgets set --workspace ID [--agent ID --cap N|none] [--new-agent-cap N|none] [--at-limit pause|ask] [--alert80 on|off]  (alert80 covers Operator and email at 80%)
+Qualification: campaigns qualification submit --file INPUT.json
+Campaign summary: campaign summary [--workspace ID]  (campaign counts per state, and per campaign its audience, offer, playbook, goal stage, people, engaged and at-goal counts)
+Find prospects: campaign find CAMPAIGN_ID --count N --max-credits C  (searches with the audience filters, checks each person, admits only fits; stops at N fits or the credit cap and reports the spend)
+                campaign check CAMPAIGN_ID --url LINKEDIN_URL [--request-id UUID]  (checks one person the same way; reuse the request ID after an interruption)
+Target companies: campaign targets CAMPAIGN_ID [--limit N --after CURSOR]  (reads the companies people must work at to join)
+                  campaign targets CAMPAIGN_ID --add acme.com,linkedin.com/company/globex [--remove old.com] | --set FILE|-  (one company per line; saves a new revision)
+Playbooks: playbook list [--archived] [--limit N --cursor ID]|actions|show ID [--revision N]|save --file REQUEST.json|archive ID|restore ID|delete ID|progress PARTICIPATION_ID|record --file REQUEST.json|suggest --file REQUEST.json|suggestions|decide --file REQUEST.json  (audienti playbook SUBCOMMAND --help for the request shape)
+Analytics: analytics show --from ISO --to ISO [--campaign ID] [--playbook-version ID] [--format json|csv]
+           analytics outbound [--workspace ID] [--days N | --from ISO --to ISO] [--by sender|action|day] [--format json|csv]
+           analytics activity [--workspace ID] [--days N | --from ISO --to ISO] [--format json|csv]
+           analytics cohorts [--workspace ID] [--stage goal|KEY] [--cohorts N] [--horizon N] [filters] [--format json|csv]
+           analytics aging [--workspace ID] [--threshold-days N] [filters] [--format json|csv]
+           analytics filters [--workspace ID]  (lists campaign, owner, offer, audience and tag values)
+           (filters: --campaign ID --owner ID --offer ID --audience ID --tag TAG; also accepted by analytics show)
+Pipeline: pipeline show [--campaign ID] [--playbook-version ID]
+Connections: connections list|register --file REQUEST.json|report --file REQUEST.json
+Discovery writes use --file INPUT.json, --workspace ID and stable --request-id UUID
+Workspace commands: workspace init|list|create|show|search|invite|invitations|use
+Notifications: workspace notifications --workspace ID [--unread-only true] [--cursor FILE.json]
+Read state: workspace notification-read --workspace ID --key KEY --read true|false [--through OBSERVED_AT]
+Search: workspace search --workspace ID --query TEXT [--people-only true] [--recent FILE.json]
+Invitation commands: workspace invitation show|accept|decline|retry|cancel ID
+Options: --workspace ID --name NAME --request-id UUID --email EMAIL --generation N
+Optional private profile: --profile PATH (outside this repository), or the AUDIENTI_PROFILE variable. --profile wins.
+Save an environment token: profile save --scope account:read|workspace:access|agents:manage --profile PATH
+Start local MCP stdio server: mcp
+--json writes the API response envelope.
+`;
+
+// Example inputs for the commands that save prospects, so `--help` shows a working shape.
+const examples = {
+  'prospects observation create': { requestId: 'UUID', kind: 'person', source: { provider: 'linkedin', url: 'https://www.linkedin.com/in/jane-doe' }, fields: { name: 'Jane Doe', title: 'VP Sales', imageUrl: 'https://media.licdn.com/dms/image/PHOTO_ID' }, provenance: { url: 'https://example.com/team/jane' }, observedAt: '2026-01-01T00:00:00Z', skill: { id: 'signal-prospect-research', version: '1' } },
+  'prospects citation create': { requestId: 'UUID', source: { kind: 'prospect', id: 'PERSON_PROSPECT_ID' }, target: { kind: 'prospect', id: 'COMPANY_PROSPECT_ID' }, edgeType: 'works_at', roles: [{ roleId: 'role-1', title: 'VP Sales', current: true, observedAt: '2026-01-01T00:00:00Z' }] },
+  'prospects evidence create': { requestId: 'UUID', subject: { kind: 'person', prospectId: 'PROSPECT_ID' }, campaignId: 'CAMPAIGN_ID', campaignRevision: 1, kind: 'interpretation', data: { conclusion: 'Leads a 40-person sales team', reason: 'Team page lists her as VP Sales' }, sourceUrl: 'https://example.com/team', observedAt: '2026-01-01T00:00:00Z', skill: { id: 'signal-prospect-research', version: '1' } },
+  'prospects contacts record': { kind: 'email|linkedin|mobile|phone', value: 'jane@example.com, or +15551234567 for a mobile or a direct office phone', reason: 'Published on https://example.com/contact', requestId: 'UUID', provenance: { observationId: 'OBSERVATION_ID' } },
+  'campaigns qualification submit': { requestId: 'UUID', campaignId: 'CAMPAIGN_ID', campaignRevision: 1, prospectId: 'PERSON_PROSPECT_ID', companyProspectId: 'COMPANY_PROSPECT_ID', companyIcp: { status: 'pass|fail|unverified', evidenceIds: ['COMPANY_EVIDENCE_ID'] }, personIcp: { status: 'pass|fail|unverified', evidenceIds: ['PERSON_EVIDENCE_ID'] }, signal: { status: 'match|no_match|unverified|not_required', evidenceIds: [] }, fit: { status: 'high|moderate|low|no_fit|unscored', evidenceIds: ['PERSON_EVIDENCE_ID'], reason: 'why' }, skill: { id: 'signal-prospect-research', version: '1' } },
+};
+
+function commandHelp() {
+  const words = args.slice(0, args.findIndex(value => value.startsWith('-'))).filter(Boolean);
+  const lines = usage.split('\n');
+  let shown = [];
+  for (let n = Math.min(words.length, 2); n > 0 && shown.length === 0; n--) {
+    const prefix = words.slice(0, n).join(' ');
+    shown = lines.filter(line => line.includes(prefix));
+  }
+  console.log(shown.length ? shown.map(line => line.trim()).join('\n') : usage);
+  const example = Object.entries(examples).find(([command]) => words.join(' ').startsWith(command));
+  if (example) console.log(`\nExample --file INPUT.json for ${example[0]}:\n${JSON.stringify(example[1], null, 1)}\nSteps and rules: the "Save prospects and contacts" section of llms.txt.`);
+}
+
+async function main() {
+  if (args[0] === 'playbook' && args.slice(1).some(value => value === '--help' || value === '-h')) { console.log(playbookHelp(args[1]?.startsWith('-') ? undefined : args[1])); return; }
+  if (args.length > 1 && args.slice(1).some(value => value === '--help' || value === '-h') && !['tools', 'call', 'skills'].includes(args[0])) { commandHelp(); return; }
+  if(args[0]==='prospects'&&['intake','conversation'].includes(args[1])){const {accountIntakeCli}=await import('./account-intake.mjs');await accountIntakeCli(args);return;}
+  if(args[0]==='sender'){const {senderAccountsCli}=await import('./sender-accounts.mjs');await senderAccountsCli(args);return;}
+  if(args[0]==='prospecting'){const {prospectingSettingsCli}=await import('./prospecting-settings.mjs');await prospectingSettingsCli(args);return;}
+  if(args[0]==='prospects'&&args[1]==='replies'){const {accountRepliesCli}=await import('./account-replies.mjs');await accountRepliesCli(args);return;}
+  if(args[0]==='prospects'&&args[1]==='contacts'){const {recipientsCli}=await import('./recipients.mjs');await recipientsCli(args);return;}
+  if(args[0]==='usage'){const {usageCli}=await import('./usage.mjs');await usageCli(args);return;}
+  if(args[0]==='audit'){const {auditCli}=await import('./audit.mjs');await auditCli(args);return;}
+  if(args[0]==='secret'||args[0]==='secrets'){const {secretsCli}=await import('./secrets.mjs');await secretsCli(args);return;}
+  if(args[0]==='budgets'){const {budgetsCli}=await import('./budgets.mjs');await budgetsCli(args);return;}
+  if(args[0]==='guardrails'||args[0]==='dnc'){const {guardrailsCli}=await import('./guardrails.mjs');await guardrailsCli(args);return;}
+  if(args[0]==='prospects'&&args[1]==='suppression'){const {suppressionCli}=await import('./suppression.mjs');await suppressionCli(args);return;}
+  if(args[0]==='call'){const {callCli}=await import('./tools.mjs');await callCli(args);return;}
+  if(args[0]==='tools'){const {toolsCli}=await import('./tools.mjs');await toolsCli(args);return;}
+  if(['topics','posts'].includes(args[0])){const {contentCli}=await import('./content.mjs');await contentCli(args);return;}
+  if(args[0]==='work'&&args[1]==='execution'){const {workExecutionCli}=await import('./work-execution.mjs');await workExecutionCli(args);return;}
+  if(args[0]==='work'&&args[1]==='changes'){const {workFeedbackCli}=await import('./work-feedback.mjs');await workFeedbackCli(args);return;}
+  if(args[0]==='work'){const {workCli}=await import('./work.mjs');await workCli(args);return;}
+  if(['prospects','campaigns'].includes(args[0])){const {discoveryCli}=await import('./discovery.mjs');await discoveryCli(args);return;}
+  if(args[0]==='analytics'&&['cohorts','aging','filters'].includes(args[1])){const {cohortCli}=await import('./cohorts.mjs');await cohortCli(args);return;}
+  if(args[0]==='analytics'&&['outbound','activity'].includes(args[1])){const {outboundCli}=await import('./outbound.mjs');await outboundCli(args);return;}
+  if(['playbook','analytics','pipeline','connections'].includes(args[0])){const {progressCli}=await import('./progress.mjs');await progressCli(args);return;}
+  if(args[0]==='campaign'){const {campaignCli}=await import('./campaigns.mjs');await campaignCli(args);return;}
+  if(args[0]==='audience'){const {audienceCli}=await import('./audiences.mjs');await audienceCli(args);return;}
+  if(args[0]==='file'){const {fileCli}=await import('./files.mjs');await fileCli(args);return;}
+  if(args[0]==='ask'){const {askCli}=await import('./questions.mjs');await askCli(args);return;}
+  if(args[0]==='questions'){const {questionsCli}=await import('./questions.mjs');await questionsCli(args);return;}
+  if(args[0]==='queue'){const {queueCli}=await import('./queue.mjs');await queueCli(args);return;}
+  if(args[0]==='attachments'){const {attachmentsCli}=await import('./attachments.mjs');await attachmentsCli(args);return;}
+  if(args[0]==='outcomes'){const {outcomesCli}=await import('./outcomes.mjs');await outcomesCli(args);return;}
+  if(args[0]==='rooms'){const {roomsCli}=await import('./rooms.mjs');await roomsCli(args);return;}
+  if(args[0]==='kv'){const {kvCli}=await import('./kv.mjs');await kvCli(args);return;}
+  if(args[0]==='offer'){const {offerCli}=await import('./offers.mjs');await offerCli(args);return;}
+  if (args[0] === 'agent') { const { agentCli } = await import('./agents.mjs'); await agentCli(args); return; }
+  if (isAssignmentCommand(args)) { await assignmentCli(args); return; }
+  if (['workspace', 'profile'].includes(args[0])) { const { workspaceCli } = await import('./workspaces.mjs'); await workspaceCli(args); return; }
+  if (args[0] === 'profiles') { const { profilesCli } = await import('./profiles.mjs'); await profilesCli(args); return; }
+  if (args[0] === 'skills') { const { skillsCli } = await import('./skills.mjs'); await skillsCli(args); return; }
+  if (args[0] === 'mcp' && args.length === 1) { await import('./mcp.mjs'); return; }
+  if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]))) { console.log(usage); return; }
+  let profileConfig;
+  const profileIndex = args.indexOf('--profile');
+  if (args[0] === 'whoami' && profileIndex > 0 && args[profileIndex + 1]) {
+    const { configuration } = await import('./workspaces.mjs');
+    profileConfig = configuration(args[profileIndex + 1], 'account:read');
+    if (!profileConfig.token) throw new Error('whoami needs a human account token. Agents confirm their connection with: audienti workspace list --profile PATH');
+    args.splice(profileIndex, 2);
+  } else if (args[0] === 'whoami' && profileIndex < 0 && process.env.AUDIENTI_PROFILE && !(process.env.AUDIENTI_API_URL && process.env.AUDIENTI_API_TOKEN)) {
+    // The profile named by AUDIENTI_PROFILE (#448), unless the URL and token are in the environment.
+    const { configuration } = await import('./workspaces.mjs');
+    profileConfig = configuration(undefined, 'account:read');
+    if (!profileConfig.token) throw new Error('whoami needs a human account token, and AUDIENTI_PROFILE holds none. Agents confirm their connection with: audienti workspace list');
+  }
+  if (args[0] !== 'whoami' || args.length > 2 || (args[1] && args[1] !== '--json')) throw new Error('Unknown command or option. Use audienti --help.');
+  const rawUrl = profileConfig ? profileConfig.url : process.env.AUDIENTI_API_URL;
+  const token = profileConfig ? profileConfig.token : process.env.AUDIENTI_API_TOKEN;
+  if (!rawUrl || !token) throw new Error('Set AUDIENTI_API_URL and AUDIENTI_API_TOKEN, or pass --profile PATH (or set AUDIENTI_PROFILE) to a profile with an account:read token. Create a token from your Account page.');
+  let base;
+  try { base = new URL(rawUrl); } catch { throw new Error('AUDIENTI_API_URL must be a valid API base URL.'); }
+  if (base.username || base.password || base.search || base.hash) throw new Error('The API URL must not contain credentials, query parameters, or a fragment.');
+  const local = ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname);
+  if (base.protocol !== 'https:' && !(base.protocol === 'http:' && local)) throw new Error('Use HTTPS for remote API hosts. HTTP is only allowed on loopback.');
+  if (base.pathname.replace(/\/$/, '') !== '/api/v1') throw new Error('AUDIENTI_API_URL must end with /api/v1.');
+  base.pathname = '/api/v1/account';
+  let response;
+  try {
+    response = await fetch(base, { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(10_000) });
+  } catch { throw new Error('Could not reach the API. Check its URL and availability. Redirects are not followed.'); }
+  if (!response.ok) {
+    if (response.status === 401) throw new Error('Authentication failed. Check whether your token is invalid, expired, or revoked.');
+    if (response.status === 403) throw new Error('This token lacks account:read permission.');
+    throw new Error(`API request failed (HTTP ${response.status}).`);
+  }
+  let body;
+  try { body = await response.json(); } catch { throw new Error('The API returned an invalid response.'); }
+  const data = body?.data;
+  if (!data || typeof data.id !== 'string' || !('email' in data) || !('username' in data) || ![data.email, data.username].every(v => v === null || typeof v === 'string')) throw new Error('The API returned an invalid account profile.');
+  // Select the documented fields, so an unexpected response cannot print credentials.
+  const profile = { id: data.id, email: data.email, username: data.username };
+  console.log(args[1] === '--json' ? JSON.stringify({ data: profile }) : `${profile.email ?? profile.username ?? profile.id}\nAccount ID: ${profile.id}`);
+}
+
+main().catch(error => { console.error(JSON.stringify({ error: error.toJSON ? error.toJSON() : { code: 'client_error', message: error.message } })); process.exitCode = 1; });

package/cli/audit-operations.mjs

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+const query = a => new URLSearchParams(Object.entries(a).filter(([k, v]) => k !== 'workspaceId' && v !== undefined).map(([k, v]) => [k, String(v)]));
+export const auditOperations = {
+ workspace_audit_log_list: {
+  schema: z.object({
+   workspaceId: z.string().uuid().optional(),
+   actor: z.enum(['person', 'agent']).optional(),
+   category: z.enum(['guardrails', 'budgets', 'approvals', 'suppression', 'members', 'agents']).optional(),
+   since: z.string().datetime().optional(),
+   until: z.string().datetime().optional(),
+   cursor: z.string().max(500).optional(),
+   limit: z.number().int().min(1).max(200).optional(),
+  }).strict(),
+  method: 'GET', path: a => `/workspaces/${a.workspaceId}/audit-events?${query(a)}`, scoped: true,
+  description: 'List the read-only workspace audit log: who changed guardrails, budgets, approvals, suppression, members and agent access, newest first. Admin only. Page with cursor.',
+ },
+};

package/cli/audit.mjs

@@ -0,0 +1,39 @@
+import { callWorkspace, configuration } from './workspaces.mjs';
+
+const UNITS = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+export function sinceToIso(value, now = Date.now()) {
+ const match = /^(\d{1,4})([mhdw])$/.exec(value);
+ if (match) return new Date(now - Number(match[1]) * UNITS[match[2]]).toISOString();
+ const date = new Date(value);
+ if (Number.isNaN(date.getTime())) throw Error('--since must look like 7d, 12h or an ISO date.');
+ return date.toISOString();
+}
+const cell = value => /[",\n\r]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+export function auditCsv(items) {
+ const rows = items.map(item => [item.at, item.actor?.kind ?? '', item.actor?.name ?? '', item.category, item.action, item.summary, item.object?.label ?? '', item.object?.href ?? '']);
+ return [['when', 'actor_kind', 'actor', 'category', 'action', 'summary', 'object', 'link'], ...rows].map(row => row.map(cell).join(',')).join('\n') + '\n';
+}
+export async function auditCli(args) {
+ const flags = {}, positions = [];
+ for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--json') continue;
+  if (!arg.startsWith('--')) { positions.push(arg); continue; }
+  const key = arg.slice(2);
+  if (!['workspace', 'profile', 'since', 'until', 'actor', 'category', 'limit', 'cursor', 'format'].includes(key) || Object.hasOwn(flags, key) || i + 1 >= args.length) throw Error(`Invalid flag --${key}.`);
+  flags[key] = args[++i];
+ }
+ if (positions.length !== 2 || positions[1] !== 'list') throw Error('Use audit list [--workspace ID] [--since 7d] [--actor agent|person] [--format json|csv].');
+ if (flags.actor && !['agent', 'person'].includes(flags.actor)) throw Error('--actor must be agent or person.');
+ if (flags.format && !['json', 'csv'].includes(flags.format)) throw Error('--format must be json or csv.');
+ const input = { workspaceId: flags.workspace };
+ if (flags.actor) input.actor = flags.actor;
+ if (flags.category) input.category = flags.category;
+ if (flags.since) input.since = sinceToIso(flags.since);
+ if (flags.until) input.until = sinceToIso(flags.until);
+ if (flags.cursor) input.cursor = flags.cursor;
+ if (flags.limit) { input.limit = Number(flags.limit); if (!Number.isInteger(input.limit)) throw Error('--limit must be a whole number.'); }
+ const result = await callWorkspace('workspace_audit_log_list', input, configuration(flags.profile));
+ if (flags.format === 'csv') { process.stdout.write(auditCsv((result?.data ?? result)?.items ?? [])); return; }
+ console.log(JSON.stringify(result));
+}

package/cli/budget-operations.mjs

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+const workspace = { workspaceId: z.string().uuid().optional() };
+const cap = z.number().int().min(0).max(10000000).nullable();
+export const budgetOperations = {
+ workspace_budgets_get: { schema: z.object(workspace).strict(), method: 'GET', path: a => `/workspaces/${a.workspaceId}/budgets`, scoped: true, description: 'Read spend budgets: credits used this UTC month, each agent’s monthly cap (null means unlimited), the cap for newly registered agents, what happens at a cap and the 80% warning switch (Operator and email) and the ten latest alerts.' },
+ workspace_budget_alerts: { schema: z.object({ ...workspace, limit: z.number().int().min(1).max(200).optional() }).strict(), method: 'GET', path: a => `/workspaces/${a.workspaceId}/budget-alerts${a.limit ? `?limit=${a.limit}` : ''}`, scoped: true, description: 'List recent low-credit and budget alerts, newest first. Workspace credits and each agent’s monthly cap alert once per UTC month at 80% and at 100%; owners and admins are emailed and see them in Operator.' },
+ workspace_budgets_set: { schema: z.object({ ...workspace, agentCaps: z.array(z.object({ agentId: z.string().uuid(), monthlyCap: cap }).strict()).max(200).optional(), newAgentCap: cap.optional(), atLimit: z.enum(['pause', 'ask']).optional(), alert80: z.boolean().optional(), expectedVersion: z.number().int().min(0).optional() }).strict(), method: 'POST', path: a => `/workspaces/${a.workspaceId}/budgets`, body: ({ workspaceId, ...rest }) => rest, scoped: true, description: 'Change spend budgets. Send only the fields to change; null removes a cap. Admin only and only a person: an agent cannot raise its own cap. An agent at its cap gets budget_exceeded on hosted tool calls until the month resets or the cap is raised.' },
+};

package/cli/budgets.mjs

@@ -0,0 +1,34 @@
+import { callWorkspace, configuration } from './workspaces.mjs';
+const cap = (name, value) => {
+ if (value === 'none' || value === 'unlimited') return null;
+ if (!/^\d+$/.test(value ?? '')) throw Error(`--${name} needs a whole number of credits, or "none" for no cap.`);
+ return Number(value);
+};
+export async function budgetsCli(args) {
+ const flags = {}, positions = [];
+ for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--json') continue;
+  if (!arg.startsWith('--')) { positions.push(arg); continue; }
+  const key = arg.slice(2);
+  if (!['workspace', 'profile', 'agent', 'cap', 'new-agent-cap', 'at-limit', 'alert80', 'limit'].includes(key) || Object.hasOwn(flags, key) || i + 1 >= args.length) throw Error(`Invalid flag --${key}.`);
+  flags[key] = args[++i];
+ }
+ if (positions.length !== 2 || positions[0] !== 'budgets' || !['show', 'set', 'alerts'].includes(positions[1])) throw Error('Use budgets show|set|alerts --workspace ID. See audienti help.');
+ const input = { workspaceId: flags.workspace };
+ let name = 'workspace_budgets_get';
+ if (positions[1] === 'alerts') {
+  name = 'workspace_budget_alerts';
+  if (flags.limit !== undefined) { if (!/^\d+$/.test(flags.limit) || Number(flags.limit) < 1 || Number(flags.limit) > 200) throw Error('--limit is a whole number from 1 to 200.'); input.limit = Number(flags.limit); }
+ }
+ if (positions[1] === 'set') {
+  name = 'workspace_budgets_set';
+  if ((flags.agent === undefined) !== (flags.cap === undefined)) throw Error('--agent and --cap go together.');
+  if (flags.agent) input.agentCaps = [{ agentId: flags.agent, monthlyCap: cap('cap', flags.cap) }];
+  if (flags['new-agent-cap'] !== undefined) input.newAgentCap = cap('new-agent-cap', flags['new-agent-cap']);
+  if (flags['at-limit'] !== undefined) { if (!['pause', 'ask'].includes(flags['at-limit'])) throw Error('--at-limit is pause or ask.'); input.atLimit = flags['at-limit']; }
+  if (flags.alert80 !== undefined) { if (!['on', 'off'].includes(flags.alert80)) throw Error('--alert80 is on or off.'); input.alert80 = flags.alert80 === 'on'; }
+  if (Object.keys(input).length < 2) throw Error('Nothing to change. Use --agent ID --cap N, --new-agent-cap N, --at-limit pause|ask or --alert80 on|off.');
+ }
+ console.log(JSON.stringify(await callWorkspace(name, input, configuration(flags.profile))));
+}