feat: support pulling a single resource by UUID

Allow pull commands to target one remote resource by UUID when paired with a single resource type, and clarify the required syntax in the docs.

Author: dhruva-vapi

AGENTS.md

@@ -27,6 +27,7 @@ This project manages **Vapi voice agent configurations** as code. All resources
 | Test webhook event delivery locally | Run `npm run mock:webhook` and tunnel with ngrok                              |
 | Push changes to Vapi                | `npm run push:dev` or `npm run push:prod`                                     |
 | Pull latest from Vapi               | `npm run pull:dev`, `npm run pull:dev:force`, or `npm run pull:dev:bootstrap` |
+| Pull one known remote resource      | `npm run pull:dev -- assistants --id <uuid>`                                  |
 | Push only one file                  | `npm run push:dev resources/dev/assistants/my-agent.md`                       |
 | Test a call                         | `npm run call:dev -- -a <assistant-name>`                                     |
 
@@ -704,6 +705,8 @@ Concrete example conversations showing expected behavior.
 npm run pull:dev              # Pull from Vapi (preserve local changes)
 npm run pull:dev:force        # Pull from Vapi (overwrite everything)
 npm run pull:dev:bootstrap    # Refresh state without writing remote resources locally
+npm run pull:dev -- squads --id <uuid>  # Pull one known remote resource by UUID
+# `--id` requires exactly one resource type; it will error if omitted or combined with multiple types
 npm run push:dev              # Push all local changes to Vapi
 npm run push:dev assistants   # Push only assistants
 npm run push:dev resources/dev/assistants/my-agent.md  # Push single file

README.md

@@ -133,6 +133,34 @@ This mode:
 
 If you skip this step, `push` will automatically run the same bootstrap sync when it detects empty or stale state for the resources being applied.
 
+#### Pulling A Single Resource By UUID
+
+If you know the remote Vapi UUID for a specific resource, you can pull just that resource by combining exactly one resource type with `--id`:
+
+```bash
+# Materialize one squad locally
+npm run pull:dev -- squads --id <squad-uuid>
+
+# Refresh state only for one assistant
+npm run pull:dev:bootstrap -- assistants --id <assistant-uuid>
+```
+
+Notes:
+
+- `--id` currently supports remote Vapi UUIDs only
+- `--id` must be paired with exactly one resource type such as `assistants`, `squads`, or `tools`
+- Single-resource pull updates only the targeted resource mappings and preserves the rest of the state file
+
+This will error if you do not provide exactly one resource type:
+
+```bash
+# Invalid: no resource type
+npm run pull:dev -- --id <uuid>
+
+# Invalid: more than one resource type
+npm run pull:dev -- assistants squads --id <uuid>
+```
+
 Promotion example:
 
 ```bash

src/config.ts

@@ -11,6 +11,7 @@ import { VALID_ENVIRONMENTS, VALID_RESOURCE_TYPES } from "./types.ts";
 export interface ApplyFilter {
   resourceTypes?: ResourceType[]; // Filter by resource types
   filePaths?: string[]; // Apply only specific files
+  resourceIds?: string[]; // Pull only specific remote resource IDs
 }
 
 // Group aliases: expand a shorthand into multiple resource types
@@ -106,6 +107,8 @@ function parseFlags(): {
     result.applyFilter.resourceTypes = resolved;
   }
 
+  const resourceIds: string[] = [];
+
   // Parse file paths and positional resource types
   const filePaths: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -115,10 +118,11 @@ function parseFlags(): {
     if (
       arg === "--force" ||
       arg === "--bootstrap" ||
+      arg === "--id" ||
       arg === "--type" ||
       arg === "-t"
     ) {
-      if (arg === "--type" || arg === "-t") i++; // skip the value too
+      if (arg === "--type" || arg === "-t" || arg === "--id") i++; // skip the value too
       continue;
     }
     // Check if it's a resource type or group (positional)
@@ -139,6 +143,18 @@ function parseFlags(): {
     result.applyFilter.filePaths = filePaths;
   }
 
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--id" && args[i + 1]) {
+      resourceIds.push(args[i + 1]!);
+      i++;
+    }
+  }
+
+  if (resourceIds.length > 0) {
+    result.applyFilter.resourceIds = resourceIds;
+  }
+
   return result;
 }
 

src/pull.ts

@@ -527,6 +527,7 @@ export interface PullOptions {
   force?: boolean;
   bootstrap?: boolean;
   typeFilter?: ResourceType[];
+  resourceIds?: string[];
 }
 
 export interface PullResult {
@@ -543,23 +544,45 @@ export async function pullResourceType(
     changedFiles?: Set<string>;
     force?: boolean;
     bootstrap?: boolean;
+    resourceIds?: string[];
   } = {},
 ): Promise<PullStats> {
-  const { changedFiles, force, bootstrap } = options;
+  const { changedFiles, force, bootstrap, resourceIds } = options;
   console.log(`\n📥 Pulling ${resourceType}...`);
 
-  const resources = (await fetchAllResources(resourceType)) ?? [];
+  const allResources = (await fetchAllResources(resourceType)) ?? [];
 
-  if (!Array.isArray(resources)) {
+  if (!Array.isArray(allResources)) {
     console.log(`   ⚠️  No ${resourceType} found (API returned non-array)`);
     return { created: 0, updated: 0, skipped: 0 };
   }
 
-  console.log(`   Found ${resources.length} ${resourceType} in Vapi`);
+  let resources = allResources;
+  if (resourceIds?.length) {
+    const requestedIds = new Set(resourceIds);
+    resources = allResources.filter((resource) =>
+      requestedIds.has(resource.id),
+    );
+    const foundIds = new Set(resources.map((resource) => resource.id));
+    const missingIds = resourceIds.filter((id) => !foundIds.has(id));
+
+    console.log(
+      `   Found ${resources.length} matching ${resourceType} in Vapi (requested ${resourceIds.length})`,
+    );
+    if (missingIds.length > 0) {
+      console.log(
+        `   ⚠️  Requested IDs not found for ${resourceType}: ${missingIds.join(", ")}`,
+      );
+    }
+  } else {
+    console.log(`   Found ${resources.length} ${resourceType} in Vapi`);
+  }
 
   const reverseMap = buildReverseMap(state, resourceType);
   const credReverse = credentialReverseMap(state);
-  const newStateSection: Record<string, string> = {};
+  const newStateSection: Record<string, string> = resourceIds?.length
+    ? { ...state[resourceType] }
+    : {};
 
   let created = 0;
   let updated = 0;
@@ -672,6 +695,15 @@ export async function runPull(options: PullOptions = {}): Promise<PullResult> {
   const force = options.force ?? process.argv.includes("--force");
   const bootstrap = options.bootstrap ?? BOOTSTRAP_SYNC;
   const typeFilter = options.typeFilter ?? APPLY_FILTER.resourceTypes;
+  const resourceIds = options.resourceIds ?? APPLY_FILTER.resourceIds;
+
+  if (resourceIds?.length) {
+    if (!typeFilter?.length || typeFilter.length !== 1) {
+      throw new Error(
+        "Single-resource pull requires exactly one resource type. Example: npm run pull:dev -- squads --id <uuid>",
+      );
+    }
+  }
 
   console.log(
     "═══════════════════════════════════════════════════════════════",
@@ -683,6 +715,9 @@ export async function runPull(options: PullOptions = {}): Promise<PullResult> {
   if (typeFilter?.length) {
     console.log(`   Filter: ${typeFilter.join(", ")}`);
   }
+  if (resourceIds?.length) {
+    console.log(`   IDs: ${resourceIds.join(", ")}`);
+  }
   if (bootstrap) {
     console.log(
       "   Mode: state sync only (remote resources are not written locally)",
@@ -749,48 +784,55 @@ export async function runPull(options: PullOptions = {}): Promise<PullResult> {
       changedFiles,
       force,
       bootstrap,
+      resourceIds,
     });
   if (shouldPull("assistants"))
     stats.assistants = await pullResourceType("assistants", state, {
       changedFiles,
       force,
       bootstrap,
+      resourceIds,
     });
   if (shouldPull("structuredOutputs"))
     stats.structuredOutputs = await pullResourceType(
       "structuredOutputs",
       state,
-      { changedFiles, force, bootstrap },
+      { changedFiles, force, bootstrap, resourceIds },
     );
   if (shouldPull("squads"))
     stats.squads = await pullResourceType("squads", state, {
       changedFiles,
       force,
       bootstrap,
+      resourceIds,
     });
   if (shouldPull("personalities"))
     stats.personalities = await pullResourceType("personalities", state, {
       changedFiles,
       force,
       bootstrap,
+      resourceIds,
     });
   if (shouldPull("scenarios"))
     stats.scenarios = await pullResourceType("scenarios", state, {
       changedFiles,
       force,
       bootstrap,
+      resourceIds,
     });
   if (shouldPull("simulations"))
     stats.simulations = await pullResourceType("simulations", state, {
       changedFiles,
       force,
       bootstrap,
+      resourceIds,
     });
   if (shouldPull("simulationSuites"))
     stats.simulationSuites = await pullResourceType("simulationSuites", state, {
       changedFiles,
       force,
       bootstrap,
+      resourceIds,
     });
 
   await saveState(state);