@pixelml/agenticflow-cli 1.5.0 → 1.5.1

package/dist/bin/agenticflow.js

@@ -2,6 +2,18 @@
 /**
  * AgenticFlow CLI entry point.
  */
+// SECURITY: Some parent environments (notably certain Claude Code launch
+// aliases) set NODE_TLS_REJECT_UNAUTHORIZED=0 for their own reasons. When the
+// CLI inherits that env, Node prints a noisy and alarming warning on EVERY
+// invocation AND the CLI's HTTPS calls to api.agenticflow.ai skip cert
+// verification. We talk to a public HTTPS endpoint with a valid cert — we
+// should never opt out of TLS verification. Unset the env var before anything
+// else imports it, unless the user explicitly opts in via AF_INSECURE_TLS=1
+// (e.g. for a local dev backend with a self-signed cert).
+if (process.env["NODE_TLS_REJECT_UNAUTHORIZED"] === "0" &&
+    process.env["AF_INSECURE_TLS"] !== "1") {
+    delete process.env["NODE_TLS_REJECT_UNAUTHORIZED"];
+}
 import { runCli } from "../cli/main.js";
 runCli().catch((err) => {
     const message = err instanceof Error ? err.message : String(err);

package/dist/bin/agenticflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"agenticflow.js","sourceRoot":"","sources":["../../src/bin/agenticflow.ts"],"names":[],"mappings":";AAEA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACrB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;YACzB,MAAM,EAAE,sBAAsB;YAC9B,IAAI,EAAE,WAAW;YACjB,OAAO;SACR,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"agenticflow.js","sourceRoot":"","sources":["../../src/bin/agenticflow.ts"],"names":[],"mappings":";AAEA;;GAEG;AAEH,yEAAyE;AACzE,8EAA8E;AAC9E,2EAA2E;AAC3E,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,4EAA4E;AAC5E,0DAA0D;AAC1D,IACE,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,KAAK,GAAG;IACnD,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG,EACtC,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AACrD,CAAC;AAED,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACrB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;YACzB,MAAM,EAAE,sBAAsB;YAC9B,IAAI,EAAE,WAAW;YACjB,OAAO;SACR,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cli/changelog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAiGrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAmHrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}

package/dist/cli/changelog.js

@@ -5,6 +5,24 @@
  * and displayed after upgrade.
  */
 export const CHANGELOG = [
+    {
+        version: "1.5.1",
+        date: "2026-04-14",
+        highlights: [
+            "CLI unsets inherited NODE_TLS_REJECT_UNAUTHORIZED=0 at startup — fixes the noisy TLS warning that leaked to every invocation AND restores certificate verification for the CLI's HTTPS calls. Opt back in with AF_INSECURE_TLS=1 if you're running a local dev backend with a self-signed cert",
+            "`af agent list --name-contains <substr>` — client-side case-insensitive name filter. Stop grep-piping in busy workspaces",
+            "`af schema <resource> --field <name>` — drill into a single field's documented shape (useful for nested fields like mcp_clients, response_format, task_management_config)",
+            "`af schema agent` now documents the 12 previously-undocumented optional fields (mcp_clients, code_execution_tool_config, response_format, knowledge, skills_config, etc.) with shape hints, plus the `update` block + null_rejected_fields list (matches what `af agent update --patch` auto-strips)",
+            "`af schema workforce` — new schema entry explaining workforce create + bulk PUT /schema shape. Covers node types, edge connection_type enum (next_step | condition | ai_condition), and the agent_id requirement on type='agent' nodes",
+            "`af bootstrap --json` commands cheat-sheet now surfaces delete_agent, delete_workforce, list_agents_filtered, and get_schema_field — closes the 'how do I clean up' discoverability gap",
+        ],
+        for_ai: [
+            "Expected journey for a fresh agent operator:  (1) af whoami  →  (2) af bootstrap --json  →  (3) af playbook first-touch (or migrate-from-paperclip if coming from Paperclip)  →  (4) af schema <resource> --field <name> for any unclear payload shape  →  (5) build with --dry-run, then live  →  (6) cleanup with af <resource> delete",
+            "Use `af agent list --name-contains <substr> --fields id,name --json` to find your own test agents in a populated workspace before bulk delete",
+            "`af schema agent --field mcp_clients --json` returns the documented attach-shape with run_behavior + per-tool allow map — no more guessing",
+            "If you hit TLS cert errors against a self-signed backend, set AF_INSECURE_TLS=1 (do NOT set NODE_TLS_REJECT_UNAUTHORIZED directly — CLI now unsets it at startup)",
+        ],
+    },
     {
         version: "1.5.0",
         date: "2026-04-14",

package/dist/cli/changelog.js.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,iKAAiK;YACjK,mIAAmI;YACnI,4JAA4J;YAC5J,qJAAqJ;YACrJ,8GAA8G;YAC9G,yGAAyG;SAC1G;QACD,MAAM,EAAE;YACN,mMAAmM;YACnM,wLAAwL;YACxL,wGAAwG;YACxG,gGAAgG;YAChG,iIAAiI;YACjI,oIAAoI;SACrI;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,2GAA2G;YAC3G,+MAA+M;YAC/M,2LAA2L;YAC3L,kJAAkJ;YAClJ,2GAA2G;YAC3G,2GAA2G;YAC3G,iKAAiK;YACjK,kHAAkH;YAClH,uHAAuH;SACxH;QACD,MAAM,EAAE;YACN,6LAA6L;YAC7L,uLAAuL;YACvL,4PAA4P;YAC5P,+JAA+J;YAC/J,2GAA2G;SAC5G;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,uEAAuE;YACvE,mFAAmF;YACnF,yFAAyF;YACzF,gFAAgF;YAChF,kEAAkE;YAClE,uFAAuF;YACvF,iEAAiE;YACjE,uEAAuE;YACvE,yDAAyD;YACzD,wDAAwD;YACxD,6EAA6E;YAC7E,6GAA6G;SAC9G;QACD,MAAM,EAAE;YACN,6FAA6F;YAC7F,+GAA+G;YAC/G,qFAAqF;YACrF,6EAA6E;YAC7E,qEAAqE;YACrE,oHAAoH;YACpH,wGAAwG;YACxG,mGAAmG;SACpG;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,gEAAgE;YAChE,uEAAuE;YACvE,mDAAmD;YACnD,4CAA4C;SAC7C;QACD,MAAM,EAAE;YACN,6CAA6C;YAC7C,6DAA6D;SAC9D;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,kCAAkC;YAClC,6CAA6C;YAC7C,qCAAqC;SACtC;QACD,MAAM,EAAE;YACN,0CAA0C;SAC3C;KACF;CACF,CAAC;AAEF,MAAM,UAAU,kBAAkB;IAChC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC9D,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,gSAAgS;YAChS,0HAA0H;YAC1H,2KAA2K;YAC3K,sSAAsS;YACtS,wOAAwO;YACxO,yLAAyL;SAC1L;QACD,MAAM,EAAE;YACN,0UAA0U;YAC1U,+IAA+I;YAC/I,4IAA4I;YAC5I,mKAAmK;SACpK;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,iKAAiK;YACjK,mIAAmI;YACnI,4JAA4J;YAC5J,qJAAqJ;YACrJ,8GAA8G;YAC9G,yGAAyG;SAC1G;QACD,MAAM,EAAE;YACN,mMAAmM;YACnM,wLAAwL;YACxL,wGAAwG;YACxG,gGAAgG;YAChG,iIAAiI;YACjI,oIAAoI;SACrI;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,2GAA2G;YAC3G,+MAA+M;YAC/M,2LAA2L;YAC3L,kJAAkJ;YAClJ,2GAA2G;YAC3G,2GAA2G;YAC3G,iKAAiK;YACjK,kHAAkH;YAClH,uHAAuH;SACxH;QACD,MAAM,EAAE;YACN,6LAA6L;YAC7L,uLAAuL;YACvL,4PAA4P;YAC5P,+JAA+J;YAC/J,2GAA2G;SAC5G;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,uEAAuE;YACvE,mFAAmF;YACnF,yFAAyF;YACzF,gFAAgF;YAChF,kEAAkE;YAClE,uFAAuF;YACvF,iEAAiE;YACjE,uEAAuE;YACvE,yDAAyD;YACzD,wDAAwD;YACxD,6EAA6E;YAC7E,6GAA6G;SAC9G;QACD,MAAM,EAAE;YACN,6FAA6F;YAC7F,+GAA+G;YAC/G,qFAAqF;YACrF,6EAA6E;YAC7E,qEAAqE;YACrE,oHAAoH;YACpH,wGAAwG;YACxG,mGAAmG;SACpG;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,gEAAgE;YAChE,uEAAuE;YACvE,mDAAmD;YACnD,4CAA4C;SAC7C;QACD,MAAM,EAAE;YACN,6CAA6C;YAC7C,6DAA6D;SAC9D;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,kCAAkC;YAClC,6CAA6C;YAC7C,qCAAqC;SACtC;QACD,MAAM,EAAE;YACN,0CAA0C;SAC3C;KACF;CACF,CAAC;AAEF,MAAM,UAAU,kBAAkB;IAChC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC9D,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAy4BpC,wBAAgB,aAAa,IAAI,OAAO,CA2pKvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAy4BpC,wBAAgB,aAAa,IAAI,OAAO,CAwvKvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}

package/dist/cli/main.js

@@ -767,16 +767,63 @@ export function createProgram() {
                     system_prompt: "string",
                     recursion_limit: "number (10-500, default: 25)",
                     agent_type: "standard | autonomous (default: standard)",
+                    model_user_config: "object { temperature?, max_tokens?, max_input_tokens?, reasoning_effort? }",
+                    mcp_clients: "array of { mcp_client_id, run_behavior: 'auto_run' | 'confirm', description?, timeout?, tools?: {tool_name: {allowed: bool}} } — attach MCP tool providers",
+                    code_execution_tool_config: "object { enable: bool, enable_file_operations?: bool } — enable Python/JS code exec",
+                    file_system_tool_config: "object | null — enable file system tool",
+                    attachment_config: "object | null — file attachment config",
+                    response_format: "object | null — structured output schema for the agent's final response (JSON mode)",
+                    knowledge: "object | null — knowledge base / RAG configuration",
+                    skills_config: "object | null — skill pack configuration",
+                    task_management_config: "object | null — task queue / scheduling configuration",
+                    suggest_replies: "bool (default: true) — generate suggested follow-up replies",
+                    auto_generate_title: "bool (default: true) — auto-title new threads",
+                    welcome_message: "string — greeting on new thread",
+                    suggested_messages: "array of strings — pre-populated example prompts shown to users",
+                    sub_agents: "array — sub-agent configurations for agent teams",
+                    plugins: "array — plugin configurations",
                 },
                 example: { name: "My Agent", tools: [], project_id: "YOUR_PROJECT_ID" },
             },
+            update: {
+                note: "PUT /v1/agents/{id} — supply any subset of create fields. Prefer `af agent update --patch` to avoid round-tripping the full body.",
+                null_rejected_fields: [
+                    "suggest_replies_model", "suggest_replies_model_user_config", "suggest_replies_prompt_template",
+                    "knowledge", "task_management_config", "recursion_limit",
+                    "file_system_tool_config", "attachment_config", "response_format", "skills_config",
+                ],
+                null_rejected_note: "These fields must be OMITTED (not sent as null) on update — server rejects null. The CLI auto-strips when you use `af agent update` (with or without --patch).",
+            },
             stream: {
                 required: ["messages"],
                 optional: { id: "string (thread UUID for conversation continuity)" },
                 messages_item: { required: ["content"], optional: { role: "user (default)" } },
                 example: { messages: [{ content: "Hello", role: "user" }] },
             },
-            fields: ["id", "name", "description", "model", "visibility", "system_prompt", "tools", "mcp_clients", "plugins", "sub_agents", "agent_type", "recursion_limit", "created_at", "updated_at"],
+            fields: ["id", "name", "description", "model", "visibility", "system_prompt", "tools", "mcp_clients", "plugins", "sub_agents", "agent_type", "recursion_limit", "model_user_config", "code_execution_tool_config", "file_system_tool_config", "attachment_config", "response_format", "knowledge", "skills_config", "task_management_config", "suggest_replies", "auto_generate_title", "welcome_message", "suggested_messages", "created_at", "updated_at"],
+        },
+        workforce: {
+            resource: "workforce",
+            note: "AgenticFlow-native multi-agent DAG (nodes + edges). Create metadata first, then PUT /schema with the full graph.",
+            create: {
+                required: ["name"],
+                optional: {
+                    description: "string",
+                    recursion_limit: "number (default: 25)",
+                    error_handling_policy: "object { on_error: 'stop' | 'continue' | 'route', ... }",
+                    is_public: "bool (default: false)",
+                },
+                example: { name: "My Team Workforce", description: "What this team does" },
+                server_injects: "workspace_id and project_id are auto-injected from client config if absent",
+            },
+            schema: {
+                note: "PUT /v1/workspaces/{ws}/workforce/{id}/schema — atomic bulk graph replace. Server diffs current vs desired and applies create/update/delete.",
+                required: ["nodes", "edges"],
+                node_shape: { name: "string", type: "trigger | agent | output | router | condition | loop | tool | plugin | agent_team | agent_team_member | state_modifier", position: "{ x, y }", input: "object (per node_type)", meta: "object (optional)" },
+                edge_shape: { source_node_name: "string", target_node_name: "string", connection_type: "next_step | condition | ai_condition" },
+                agent_node_input: "type='agent' nodes REQUIRE a real agent_id in input. Create agents first, then reference.",
+            },
+            fields: ["id", "workspace_id", "project_id", "name", "description", "error_handling_policy", "is_public", "public_key", "current_version_id", "recursion_limit", "created_at", "updated_at"],
         },
         workflow: {
             resource: "workflow",
@@ -888,14 +935,18 @@ export function createProgram() {
                 run_agent: "af agent run --agent-id <id> --message <msg> --json",
                 create_agent: "af agent create --body <json> --dry-run --json",
                 list_agents: "af agent list --fields id,name,model --json",
+                list_agents_filtered: "af agent list --name-contains <substr> --fields id,name --json",
                 update_agent_patch: "af agent update --agent-id <id> --patch --body '{\"field\":\"value\"}' --json",
+                delete_agent: "af agent delete --agent-id <id> --json",
                 init_workforce: "af workforce init --blueprint <id> --json",
                 run_workforce: "af workforce run --workforce-id <id> --trigger-data '{}'",
                 publish_workforce: "af workforce publish --workforce-id <id> --json",
+                delete_workforce: "af workforce delete --workforce-id <id> --json",
                 inspect_mcp_client: "af mcp-clients inspect --id <id> --json",
                 deploy_to_paperclip: "af paperclip init --blueprint <id> --json   # DEPRECATED, use `af workforce init`",
                 send_webhook: "curl -X POST http://localhost:4100/webhook/webhook -H 'Content-Type: application/json' -d '{\"agent_id\":\"<id>\",\"message\":\"<msg>\"}'",
                 get_schema: "af schema <resource> --json",
+                get_schema_field: "af schema <resource> --field <field_name> --json",
                 get_playbook: "af playbook <topic>",
                 get_changelog: "af changelog --json",
             },
@@ -1019,14 +1070,15 @@ export function createProgram() {
     program
         .command("schema [resource]")
         .description("Show resource schema for payload construction. AI agents: use this to discover fields before building payloads.")
-        .action((resource) => {
+        .option("--field <name>", "Drill into a single field — returns its documented shape from create.optional (or create.required). Useful for nested fields like `mcp_clients`, `response_format`, `task_management_config`.")
+        .action((resource, opts) => {
         if (!resource) {
             if (isJsonFlagEnabled()) {
                 printResult({
                     schema: "agenticflow.schema.index.v1",
                     available: Object.keys(SCHEMAS),
                     usage: "af schema <resource> --json",
-                    hint: "Use 'af schema agent' to see agent create/stream payload schemas.",
+                    hint: "Use 'af schema agent' to see agent create/stream payload schemas. Use 'af schema agent --field mcp_clients' to drill into a single field.",
                 });
             }
             else {
@@ -1042,6 +1094,44 @@ export function createProgram() {
         if (!schema) {
             fail("schema_not_found", `Unknown resource: ${resource}`, `Available: ${Object.keys(SCHEMAS).join(", ")}`);
         }
+        // Field drilldown: return just the docs for one field
+        if (opts?.field) {
+            const fieldName = opts.field;
+            const s = schema;
+            const create = s.create ?? {};
+            const required = create.required ?? [];
+            const optional = create.optional ?? {};
+            let doc = null;
+            let isRequired = false;
+            if (required.includes(fieldName)) {
+                doc = "required";
+                isRequired = true;
+            }
+            if (fieldName in optional)
+                doc = optional[fieldName] ?? null;
+            const result = {
+                schema: "agenticflow.schema.field.v1",
+                resource: s.resource,
+                field: fieldName,
+                required: isRequired,
+                doc,
+                found: doc !== null,
+                hint: doc === null
+                    ? `Field '${fieldName}' has no documented shape in the static schema. For live introspection, fetch an existing instance via 'af ${s.resource} get --${s.resource}-id <id> --json' and inspect the returned value for that field.`
+                    : undefined,
+            };
+            if (isJsonFlagEnabled()) {
+                printResult(result);
+            }
+            else {
+                console.log(`${s.resource}.${fieldName}${isRequired ? " (required)" : " (optional)"}`);
+                if (doc)
+                    console.log(`  ${doc}`);
+                if (result.hint)
+                    console.log(`  ${result.hint}`);
+            }
+            return;
+        }
         if (isJsonFlagEnabled()) {
             printResult(schema);
         }
@@ -3328,7 +3418,8 @@ export function createProgram() {
         .command("list")
         .description("List agents.")
         .option("--project-id <id>", "Project ID")
-        .option("--search <query>", "Search query")
+        .option("--search <query>", "Backend search query (server-side)")
+        .option("--name-contains <substr>", "Client-side case-insensitive substring filter on agent `name`. Use for quick filtering in busy workspaces.")
         .option("--limit <n>", "Limit results")
         .option("--offset <n>", "Offset")
         .option("--fields <fields>", "Comma-separated fields to return (e.g. id,name,model)")
@@ -3340,7 +3431,16 @@ export function createProgram() {
             limit: parseOptionalInteger(opts.limit, "--limit", 1),
             offset: parseOptionalInteger(opts.offset, "--offset", 0),
         });
-        printResult(applyFieldsFilter(data, opts.fields));
+        let filtered = data;
+        const nameContains = opts.nameContains;
+        if (nameContains && Array.isArray(data)) {
+            const needle = nameContains.toLowerCase();
+            filtered = data.filter((row) => {
+                const n = row["name"];
+                return typeof n === "string" && n.toLowerCase().includes(needle);
+            });
+        }
+        printResult(applyFieldsFilter(filtered, opts.fields));
     });
     agentCmd
         .command("get")