@vellumai/assistant 0.4.34 → 0.4.36

package/src/cli/influencer.ts

@@ -61,6 +61,21 @@ export function registerInfluencerCommand(program: Command): void {
     )
     .option("--json", "Machine-readable JSON output");
 
+  inf.addHelpText(
+    "after",
+    `
+Researches influencers via the Chrome extension relay, which automates
+browsing on each platform. The user must be logged into each target
+platform (Instagram, TikTok, X/Twitter) in Chrome for the relay to work.
+
+Supported platforms: instagram, tiktok, twitter (X).
+
+Examples:
+  $ vellum influencer search "fitness coach" --platforms instagram,tiktok
+  $ vellum influencer profile natgeo --platform instagram
+  $ vellum influencer compare instagram:nike twitter:nike tiktok:nike`,
+  );
+
   // =========================================================================
   // search — search for influencers across platforms
   // =========================================================================
@@ -88,6 +103,27 @@ export function registerInfluencerCommand(program: Command): void {
     )
     .option("--limit <n>", "Max results per platform", "10")
     .option("--verified", "Only return verified accounts")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  query   Search query — niche, topic, or keywords (e.g. "fitness coach")
+
+--platforms filters which platforms to search. Defaults to all three:
+instagram, tiktok, twitter. Provide a comma-separated list to narrow.
+
+--min-followers and --max-followers accept human-friendly notation:
+  10k = 10,000    1.5m = 1,500,000    100k = 100,000
+Plain integers are also accepted (e.g. 50000).
+
+--limit caps the number of results returned per platform (default: 10).
+--verified restricts results to verified/blue-check accounts only.
+
+Examples:
+  $ vellum influencer search "vegan food" --min-followers 10k --max-followers 1m
+  $ vellum influencer search "tech reviewer" --platforms tiktok --limit 5 --verified
+  $ vellum influencer search "streetwear" --platforms instagram,twitter --min-followers 50k`,
+    )
     .action(
       async (
         query: string,
@@ -147,6 +183,23 @@ export function registerInfluencerCommand(program: Command): void {
       "Platform (instagram, tiktok, or twitter)",
       "instagram",
     )
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  username   The influencer's handle without the @ prefix (e.g. "natgeo", not "@natgeo")
+
+--platform selects which platform to look up. Defaults to instagram.
+Valid values: instagram, tiktok, twitter.
+
+Returns detailed profile data including follower count, bio, engagement
+metrics, and recent post statistics.
+
+Examples:
+  $ vellum influencer profile natgeo --platform instagram
+  $ vellum influencer profile charlidamelio --platform tiktok
+  $ vellum influencer profile elonmusk --platform twitter`,
+    )
     .action(
       async (username: string, opts: { platform: string }, cmd: Command) => {
         await run(cmd, async () => {
@@ -187,6 +240,25 @@ export function registerInfluencerCommand(program: Command): void {
       "<influencers...>",
       "Space-separated list of platform:username pairs (e.g. instagram:nike twitter:nike tiktok:nike)",
     )
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  influencers   Space-separated platform:username pairs (e.g. instagram:nike twitter:nike)
+
+Each argument must be in platform:username format. Valid platforms:
+instagram, tiktok, twitter. If no platform prefix is provided, defaults
+to instagram.
+
+Returns side-by-side profile data for all specified influencers,
+useful for comparing follower counts, engagement rates, and content
+metrics across platforms or between competing accounts.
+
+Examples:
+  $ vellum influencer compare instagram:nike twitter:nike tiktok:nike
+  $ vellum influencer compare instagram:natgeo instagram:discoverearth
+  $ vellum influencer compare tiktok:charlidamelio tiktok:addisonre`,
+    )
     .action(async (influencers: string[], _opts: unknown, cmd: Command) => {
       await run(cmd, async () => {
         const parsed = influencers.map((inf) => {

package/src/cli/integrations.ts

@@ -10,7 +10,6 @@ import {
   mintEdgeRelayToken,
 } from "../runtime/auth/token-service.js";
 
-type IngressChannel = "telegram" | "voice" | "sms";
 type GuardianChannel = "telegram" | "voice" | "sms";
 
 function asRecord(value: unknown): Record<string, unknown> {
@@ -20,7 +19,7 @@ function asRecord(value: unknown): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 
-function shouldOutputJson(cmd: Command): boolean {
+export function shouldOutputJson(cmd: Command): boolean {
   let current: Command | null = cmd;
   while (current) {
     if ((current.opts() as { json?: boolean }).json) return true;
@@ -29,7 +28,7 @@ function shouldOutputJson(cmd: Command): boolean {
   return false;
 }
 
-function writeOutput(cmd: Command, payload: unknown): void {
+export function writeOutput(cmd: Command, payload: unknown): void {
   const compact = shouldOutputJson(cmd);
   process.stdout.write(
     compact
@@ -49,7 +48,9 @@ function getGatewayToken(): string {
   return mintEdgeRelayToken();
 }
 
-function toQueryString(params: Record<string, string | undefined>): string {
+export function toQueryString(
+  params: Record<string, string | undefined>,
+): string {
   const query = new URLSearchParams();
   for (const [key, value] of Object.entries(params)) {
     if (value) query.set(key, value);
@@ -107,7 +108,7 @@ function readVoiceConfig(): {
 // CLI-specific gateway helper — uses GATEWAY_AUTH_TOKEN env var for out-of-process
 // access. See runtime/gateway-internal-client.ts for daemon-internal usage which
 // mints fresh tokens.
-async function gatewayGet(path: string): Promise<unknown> {
+export async function gatewayGet(path: string): Promise<unknown> {
   const gatewayBase = getGatewayInternalBaseUrl();
   const token = getGatewayToken();
 
@@ -141,7 +142,46 @@ async function gatewayGet(path: string): Promise<unknown> {
   return parsed;
 }
 
-async function runRead(
+export async function gatewayPost(
+  path: string,
+  body: unknown,
+): Promise<unknown> {
+  const gatewayBase = getGatewayInternalBaseUrl();
+  const token = getGatewayToken();
+
+  const response = await fetch(`${gatewayBase}${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  const rawBody = await response.text();
+  let parsed: unknown = { ok: false, error: rawBody };
+
+  if (rawBody.length > 0) {
+    try {
+      parsed = JSON.parse(rawBody) as unknown;
+    } catch {
+      parsed = { ok: false, error: rawBody };
+    }
+  }
+
+  if (!response.ok) {
+    const message =
+      typeof parsed === "object" && parsed && "error" in parsed
+        ? String((parsed as { error?: unknown }).error)
+        : `Gateway request failed (${response.status})`;
+    throw new Error(`${message} [${response.status}]`);
+  }
+
+  return parsed;
+}
+
+export async function runRead(
   cmd: Command,
   reader: () => Promise<unknown>,
 ): Promise<void> {
@@ -155,70 +195,64 @@ async function runRead(
   }
 }
 
-export function registerContactsCommand(program: Command): void {
-  const contacts = program
-    .command("contacts")
-    .description("Manage and query the contact graph")
-    .option("--json", "Machine-readable compact JSON output");
-
-  contacts
-    .command("list")
-    .description("List contacts (calls /v1/contacts)")
-    .option("--role <role>", "Filter by role (default: contact)", "contact")
-    .option("--limit <limit>", "Maximum number of contacts to return")
-    .option("--query <query>", "Search query to filter contacts")
-    .action(
-      async (
-        opts: {
-          role?: string;
-          limit?: string;
-          query?: string;
-        },
-        cmd: Command,
-      ) => {
-        const query = toQueryString({
-          role: opts.role,
-          limit: opts.limit,
-          query: opts.query,
-        });
-        await runRead(cmd, async () => gatewayGet(`/v1/contacts${query}`));
-      },
-    );
-
-  contacts
-    .command("invites")
-    .description("List contact invites")
-    .option("--source-channel <sourceChannel>", "Filter by source channel")
-    .option("--status <status>", "Filter by invite status")
-    .action(
-      async (
-        opts: { sourceChannel?: IngressChannel; status?: string },
-        cmd: Command,
-      ) => {
-        const query = toQueryString({
-          sourceChannel: opts.sourceChannel,
-          status: opts.status,
-        });
-        await runRead(cmd, async () =>
-          gatewayGet(`/v1/contacts/invites${query}`),
-        );
-      },
-    );
-}
-
 export function registerIntegrationsCommand(program: Command): void {
   const integrations = program
     .command("integrations")
     .description("Read integration and ingress status through the gateway API")
     .option("--json", "Machine-readable compact JSON output");
 
+  integrations.addHelpText(
+    "after",
+    `
+Reads integration configuration and status through the gateway API. The
+assistant must be running for most subcommands (telegram, twilio, guardian)
+since they query the gateway. Exceptions: "ingress config" and "voice config"
+read from the local config file and do not require the gateway.
+
+Integration categories:
+  telegram     Telegram bot configuration and webhook status
+  twilio       Twilio credentials, phone numbers, and SMS compliance
+  guardian     Guardian trust verification system for contacts
+  ingress      Public ingress URL and local gateway target (config-only)
+  voice        Voice/call readiness and ElevenLabs voice ID (config-only)
+
+Examples:
+  $ vellum integrations telegram config
+  $ vellum integrations twilio numbers
+  $ vellum integrations guardian status --channel sms`,
+  );
+
   const telegram = integrations
     .command("telegram")
     .description("Telegram integration status");
 
+  telegram.addHelpText(
+    "after",
+    `
+Checks the Telegram bot configuration status through the gateway API.
+Requires the assistant to be running.
+
+Examples:
+  $ vellum integrations telegram config
+  $ vellum integrations telegram config --json`,
+  );
+
   telegram
     .command("config")
     .description("Get Telegram integration configuration status")
+    .addHelpText(
+      "after",
+      `
+Returns the Telegram bot token status, webhook URL, and bot username from
+the gateway. Requires the assistant to be running.
+
+The response includes whether a bot token is configured, the current webhook
+endpoint, and the bot's Telegram username.
+
+Examples:
+  $ vellum integrations telegram config
+  $ vellum integrations telegram config --json`,
+    )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () =>
         gatewayGet("/v1/integrations/telegram/config"),
@@ -229,10 +263,38 @@ export function registerIntegrationsCommand(program: Command): void {
     .command("guardian")
     .description("Guardian verification status");
 
+  guardian.addHelpText(
+    "after",
+    `
+Guardian is the trust verification system for contacts. It tracks whether
+contacts on each channel have completed identity verification. Requires
+the assistant to be running.
+
+Examples:
+  $ vellum integrations guardian status
+  $ vellum integrations guardian status --channel voice`,
+  );
+
   guardian
     .command("status")
     .description("Get guardian status for a channel")
     .option("--channel <channel>", "Channel: telegram|voice|sms", "telegram")
+    .addHelpText(
+      "after",
+      `
+Returns the guardian verification state for the specified channel. Requires
+the assistant to be running.
+
+The --channel flag accepts: telegram, voice, sms. Defaults to telegram if
+not specified. The response includes whether guardian verification is active
+and the current verification state for that channel.
+
+Examples:
+  $ vellum integrations guardian status
+  $ vellum integrations guardian status --channel telegram
+  $ vellum integrations guardian status --channel voice
+  $ vellum integrations guardian status --channel sms --json`,
+    )
     .action(async (opts: { channel?: GuardianChannel }, cmd: Command) => {
       const channel = opts.channel ?? "telegram";
       await runRead(cmd, async () =>
@@ -246,9 +308,40 @@ export function registerIntegrationsCommand(program: Command): void {
     .command("twilio")
     .description("Twilio integration status");
 
+  twilio.addHelpText(
+    "after",
+    `
+Covers Twilio credential status, phone number management, and SMS regulatory
+compliance. All subcommands require the assistant to be running since they
+query the gateway API.
+
+Subcommands:
+  config          Check Twilio credential status and phone number configuration
+  numbers         List all Twilio incoming phone numbers
+  sms compliance  Check SMS regulatory compliance status
+
+Examples:
+  $ vellum integrations twilio config
+  $ vellum integrations twilio numbers
+  $ vellum integrations twilio sms compliance`,
+  );
+
   twilio
     .command("config")
     .description("Get Twilio credential and phone number status")
+    .addHelpText(
+      "after",
+      `
+Checks the Twilio credential status and phone number configuration through
+the gateway. Requires the assistant to be running.
+
+The response includes whether the Twilio account SID and auth token are
+configured, and the currently assigned phone number.
+
+Examples:
+  $ vellum integrations twilio config
+  $ vellum integrations twilio config --json`,
+    )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () =>
         gatewayGet("/v1/integrations/twilio/config"),
@@ -258,6 +351,19 @@ export function registerIntegrationsCommand(program: Command): void {
   twilio
     .command("numbers")
     .description("List Twilio incoming phone numbers")
+    .addHelpText(
+      "after",
+      `
+Lists all incoming phone numbers associated with the configured Twilio
+account. Requires the assistant to be running.
+
+Returns an array of phone number objects with their SID, phone number,
+friendly name, and capabilities.
+
+Examples:
+  $ vellum integrations twilio numbers
+  $ vellum integrations twilio numbers --json`,
+    )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () =>
         gatewayGet("/v1/integrations/twilio/numbers"),
@@ -266,9 +372,36 @@ export function registerIntegrationsCommand(program: Command): void {
 
   const twilioSms = twilio.command("sms").description("Twilio SMS status");
 
+  twilioSms.addHelpText(
+    "after",
+    `
+Covers SMS regulatory compliance for the configured Twilio account. All
+subcommands require the assistant to be running since they query the gateway API.
+
+Subcommands:
+  compliance   Check SMS regulatory compliance status
+
+Examples:
+  $ vellum integrations twilio sms compliance
+  $ vellum integrations twilio sms compliance --json`,
+  );
+
   twilioSms
     .command("compliance")
     .description("Get Twilio SMS compliance status")
+    .addHelpText(
+      "after",
+      `
+Checks the SMS regulatory compliance status for the configured Twilio
+account. Requires the assistant to be running.
+
+Returns the current compliance state, including whether the account is
+approved for SMS messaging and any outstanding compliance requirements.
+
+Examples:
+  $ vellum integrations twilio sms compliance
+  $ vellum integrations twilio sms compliance --json`,
+    )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () =>
         gatewayGet("/v1/integrations/twilio/sms/compliance"),
@@ -278,6 +411,16 @@ export function registerIntegrationsCommand(program: Command): void {
   twilio
     .command("sms-compliance")
     .description('Alias for "vellum integrations twilio sms compliance"')
+    .addHelpText(
+      "after",
+      `
+Shortcut alias for "vellum integrations twilio sms compliance". Prefer
+the canonical path for scripts and documentation.
+
+Examples:
+  $ vellum integrations twilio sms-compliance
+  $ vellum integrations twilio sms compliance   # canonical form`,
+    )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () =>
         gatewayGet("/v1/integrations/twilio/sms/compliance"),
@@ -288,18 +431,66 @@ export function registerIntegrationsCommand(program: Command): void {
     .command("ingress")
     .description("Trusted contact membership and invite status");
 
+  ingress.addHelpText(
+    "after",
+    `
+Shows the public ingress URL and local gateway target URL. Reads from the
+local config file and does not require the gateway to be running.
+
+Examples:
+  $ vellum integrations ingress config`,
+  );
+
   ingress
     .command("config")
     .description("Get public ingress URL and local gateway target")
+    .addHelpText(
+      "after",
+      `
+Shows the public ingress URL and the local gateway target URL. Reads from
+the local config file and does not require the gateway to be running.
+
+The response includes whether ingress is enabled, the configured public base
+URL (if any), and the local gateway target address. Ingress is considered
+enabled if explicitly set to true or if a publicBaseUrl is configured.
+
+Examples:
+  $ vellum integrations ingress config
+  $ vellum integrations ingress config --json`,
+    )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () => readIngressConfig());
     });
 
   const voice = integrations.command("voice").description("Voice setup status");
 
+  voice.addHelpText(
+    "after",
+    `
+Shows voice and call readiness configuration. Reads from the local config
+file and does not require the gateway to be running.
+
+Examples:
+  $ vellum integrations voice config`,
+  );
+
   voice
     .command("config")
     .description("Get voice and call readiness config")
+    .addHelpText(
+      "after",
+      `
+Shows voice and call readiness status. Reads from the local config file and
+does not require the gateway to be running.
+
+The response includes whether calls are enabled, the active ElevenLabs voice
+ID (falls back to default if not configured), whether a custom voice ID is
+set, and whether the default voice is in use.
+
+Examples:
+  $ vellum integrations voice config
+  $ vellum integrations voice config --json`,
+    )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () => readVoiceConfig());
     });

package/src/cli/keys.ts

@@ -0,0 +1,114 @@
+import type { Command } from "commander";
+
+import { API_KEY_PROVIDERS } from "../config/loader.js";
+import {
+  deleteSecureKey,
+  getSecureKey,
+  setSecureKey,
+} from "../security/secure-keys.js";
+import { getCliLogger } from "../util/logger.js";
+
+const log = getCliLogger("cli");
+
+export function registerKeysCommand(program: Command): void {
+  const keys = program
+    .command("keys")
+    .description("Manage API keys in secure storage");
+
+  keys.addHelpText(
+    "after",
+    `
+Keys are stored in secure local storage and are never written to disk in
+plaintext. Each key is identified by provider name.
+
+Known providers: ${API_KEY_PROVIDERS.join(", ")}
+
+Examples:
+  $ vellum keys list
+  $ vellum keys set anthropic sk-ant-...
+  $ vellum keys delete openai`,
+  );
+
+  keys
+    .command("list")
+    .description("List all stored API key names")
+    .addHelpText(
+      "after",
+      `
+Checks each known provider (${API_KEY_PROVIDERS.join(", ")}) and prints the
+names of providers that have a stored key. Providers without a stored key are
+omitted from the output.
+
+Examples:
+  $ vellum keys list`,
+    )
+    .action(() => {
+      const stored: string[] = [];
+      for (const provider of API_KEY_PROVIDERS) {
+        const value = getSecureKey(provider);
+        if (value) stored.push(provider);
+      }
+      if (stored.length === 0) {
+        log.info("No API keys stored");
+      } else {
+        for (const name of stored) {
+          log.info(`  ${name}`);
+        }
+      }
+    });
+
+  keys
+    .command("set <provider> <key>")
+    .description("Store an API key (e.g. vellum keys set anthropic sk-ant-...)")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  provider   Provider name (e.g. anthropic, openai, gemini)
+  key        The API key value to store
+
+If a key already exists for the given provider, it is silently overwritten.
+
+Examples:
+  $ vellum keys set anthropic sk-ant-abc123
+  $ vellum keys set openai sk-proj-xyz789
+  $ vellum keys set fireworks fw-abc123`,
+    )
+    .action((provider: string, key: string) => {
+      if (setSecureKey(provider, key)) {
+        log.info(`Stored API key for "${provider}"`);
+      } else {
+        log.error(`Failed to store API key for "${provider}"`);
+        process.exit(1);
+      }
+    });
+
+  keys
+    .command("delete <provider>")
+    .description("Delete a stored API key")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  provider   Provider name whose key should be removed from secure storage
+
+Removes the API key for the given provider from secure local storage. If
+no key exists for the provider, exits with an error.
+
+Examples:
+  $ vellum keys delete openai
+  $ vellum keys delete anthropic`,
+    )
+    .action((provider: string) => {
+      const result = deleteSecureKey(provider);
+      if (result === "deleted") {
+        log.info(`Deleted API key for "${provider}"`);
+      } else if (result === "error") {
+        log.error(`Failed to delete API key for "${provider}": storage error`);
+        process.exit(1);
+      } else {
+        log.error(`No API key found for "${provider}"`);
+        process.exit(1);
+      }
+    });
+}