@guildai/cli 0.5.13 → 0.6.1

package/README.md

@@ -183,6 +183,23 @@ guild trigger deactivate <trigger-id>   # Deactivate a trigger
 guild trigger sessions <trigger-id>     # List sessions spawned by a trigger
 ```
 
+### Integrations
+
+```bash
+guild integration list                  # List integrations
+guild integration get <id>              # Get integration details
+guild integration create <name>         # Create a new integration
+guild integration update <id>           # Update an integration
+guild integration version list <id>     # List versions
+guild integration version create <id>   # Create a draft version
+guild integration version get <id>      # Get version details
+guild integration version build <id>    # Build (validate) a draft
+guild integration version publish <id>  # Publish a built version
+guild integration version test <id>     # Test an endpoint invocation
+guild integration operation list <id>   # List operations for a version
+guild integration operation create <id> # Create operations (or import from OpenAPI)
+```
+
 ### Chat
 
 ```bash

package/dist/commands/agent/chat.js

@@ -38,13 +38,29 @@ export function createAgentChatCommand() {
         .option('--no-splash', 'Skip the splash screen animation')
         .option('--resume <session-id>', 'Resume an existing session')
         .option('--open', 'Open session in web dashboard')
-        .addHelpText('after', '\nFor general chat with the Guild assistant, use: guild chat')
+        .addHelpText('after', '\nTo chat with a published agent by name: guild chat --agent owner/agent-name')
         .action(async (promptArgs, options) => {
         try {
             // Get agent ID from guild.json in the specified path
             const agentPath = options.path || '.';
             const { agentId, config } = await getAgentId(undefined, agentPath);
             const initialPrompt = promptArgs.length > 0 ? promptArgs.join(' ') : 'Hello';
+            // If using JSON input, read it early (before auth) for fast failure on bad input
+            let inputData;
+            if (options.mode === 'json') {
+                try {
+                    inputData = await readStdinAsJSON();
+                }
+                catch (error) {
+                    const err = error;
+                    console.error(`Error: ${err.message}`);
+                    console.error('');
+                    console.error('Example usage:');
+                    console.error('  echo \'{"prompt": "test"}\' | guild agent chat --mode json');
+                    console.error('  guild agent chat --mode json < input.json');
+                    process.exit(1);
+                }
+            }
             // Check authentication (uses shared function from chat.tsx)
             await ensureAuthenticated();
             const client = new GuildAPIClient();
@@ -152,25 +168,14 @@ export function createAgentChatCommand() {
                 console.error(`  guild agent chat ${agentId}`);
                 process.exit(1);
             }
-            // If using JSON input, read it early (before session creation)
-            let inputData;
-            if (options.mode === 'json') {
-                try {
-                    inputData = await readStdinAsJSON();
-                }
-                catch (error) {
-                    const err = error;
-                    console.error(`Error: ${err.message}`);
-                    console.error('');
-                    console.error('Example usage:');
-                    console.error('  echo \'{"prompt": "test"}\' | guild agent chat --mode json');
-                    console.error('  guild agent chat --mode json < input.json');
-                    process.exit(1);
-                }
-            }
             // Branch: JSON/JSONL modes vs interactive
             if (options.mode === 'json' || options.mode === 'jsonl') {
-                const session = await createSession(client, options.workspace, initialPrompt, version.id);
+                // For JSON mode with piped input, use the piped data as the initial prompt
+                // so the agent receives it as its input (not the default 'Hello')
+                const sessionPrompt = options.mode === 'json' && inputData
+                    ? JSON.stringify(inputData)
+                    : initialPrompt;
+                const session = await createSession(client, options.workspace, sessionPrompt, version.id);
                 if (!quiet) {
                     console.log(`✓ Agent: ${config?.name || agentId}`);
                     const sessionLink = session.session_url
@@ -183,13 +188,10 @@ export function createAgentChatCommand() {
                     await open(session.session_url);
                 }
                 if (options.mode === 'json' && inputData) {
-                    // JSON one-shot mode
+                    // JSON one-shot mode — input was passed as initial_prompt during
+                    // session creation, so the agent already has it. Just poll for the response.
                     try {
-                        await client.post(`/sessions/${session.id}/events`, {
-                            mode: 'json',
-                            content: inputData,
-                        });
-                        const response = await pollForResponse(client, session.id, 0);
+                        const { response } = await pollForResponse(client, session.id, undefined);
                         if (!response) {
                             console.error('Timeout: No response received from agent');
                             process.exit(1);
@@ -219,7 +221,7 @@ export function createAgentChatCommand() {
                     });
                     let lineNumber = 0;
                     let processedCount = 0;
-                    let lastEventCount = 0;
+                    let lastEventId;
                     for await (const line of rl) {
                         lineNumber++;
                         if (!line.trim())
@@ -233,15 +235,13 @@ export function createAgentChatCommand() {
                                 mode: 'json',
                                 content: jsonInput,
                             });
-                            const response = await pollForResponse(client, session.id, lastEventCount);
-                            if (!response) {
+                            const result = await pollForResponse(client, session.id, lastEventId);
+                            lastEventId = result.lastEventId;
+                            if (!result.response) {
                                 console.error(`Timeout: No response for line ${lineNumber}`);
-                                const eventsAfterResponse = await client.get(`/sessions/${session.id}/events`);
-                                lastEventCount = eventsAfterResponse?.items?.length || 0;
                                 continue;
                             }
-                            const eventsAfterResponse = await client.get(`/sessions/${session.id}/events`);
-                            lastEventCount = eventsAfterResponse?.items?.length || 0;
+                            const response = result.response;
                             if (quiet) {
                                 console.log(response);
                             }

package/dist/commands/agent/clone.js

@@ -8,6 +8,7 @@ import * as path from 'path';
 import { getAuthenticatedUrl } from '../../lib/auth.js';
 import { runGit, GitError, formatGitError, installPrePushHook } from '../../lib/git.js';
 import { createOutputWriter } from '../../lib/output.js';
+import { resolveAgentRef } from '../../lib/agent-helpers.js';
 async function isDirectoryEmpty(dirPath) {
     try {
         const files = await fs.readdir(dirPath);
@@ -30,7 +31,8 @@ export function createAgentCloneCommand() {
         try {
             // Fetch agent details
             const client = new GuildAPIClient();
-            const agent = await client.get(`/agents/${agentId}`);
+            const resolvedId = await resolveAgentRef(client, agentId);
+            const agent = await client.get(`/agents/${resolvedId}`);
             if (!agent.git_url) {
                 output.error('Error: Agent does not have a git repository', 'This agent may not have been initialized with git.');
                 process.exit(1);

package/dist/commands/agent/code.js

@@ -3,7 +3,7 @@
 import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
-import { getAgentId } from '../../lib/agent-helpers.js';
+import { getAgentId, resolveAgentRef } from '../../lib/agent-helpers.js';
 import { createOutputWriter } from '../../lib/output.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
@@ -22,7 +22,8 @@ export function createAgentCodeCommand() {
         const includeDraft = options.draft ? '1' : '0';
         let files;
         try {
-            files = await client.get(`/agents/${agentId}/code?include_unpublished=${includeDraft}`);
+            const resolvedId = await resolveAgentRef(client, agentId);
+            files = await client.get(`/agents/${resolvedId}/code?include_unpublished=${includeDraft}`);
         }
         catch (error) {
             const formattedError = handleAxiosError(error);

package/dist/commands/agent/fork.js

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAgentId, resolveAgentRef } from '../../lib/agent-helpers.js';
 import { handleAxiosError, ErrorCodes, debug } from '../../lib/errors.js';
 import * as fs from 'fs/promises';
 import * as readline from 'readline';
@@ -47,21 +48,48 @@ export function createAgentForkCommand() {
     const cmd = new Command('fork');
     cmd
         .description('Fork an existing agent version to create a new agent')
-        .argument('<agent-id>:<version-id>', 'Source agent and version (e.g., agent_abc:version_xyz)')
+        .argument('[identifier]', 'Agent ID, full name, or agent:version (e.g., owner/agent-name:version_xyz)')
         .option('--name <name>', 'Name for the forked agent')
         .option('--description <desc>', 'Description for the forked agent')
         .option('--directory <path>', 'Target directory for clone')
-        .option('--owner <owner-id>', 'Owner account (user or organization ID)')
-        .action(async (sourceArg, options) => {
+        .option('--owner <owner>', 'Owner (name or ID)')
+        .action(async (identifierArg, options) => {
         const output = createOutputWriter();
         try {
-            // Parse agent-id:version-id format
-            const parts = sourceArg.split(':');
-            if (parts.length !== 2 || !parts[0] || !parts[1]) {
-                output.error('Error: Invalid argument format', `Expected: <agent-id>:<version-id>\nExample: guild agent fork agent_abc123:version_xyz789\n\nTo find versions:\n  guild agent versions ${parts[0] || '<agent-id>'}`);
-                process.exit(1);
+            // Resolve agent ID and optional version ID
+            let sourceAgentId;
+            let sourceVersionId;
+            if (identifierArg && identifierArg.includes(':')) {
+                // Explicit agent:version format
+                const colonIndex = identifierArg.lastIndexOf(':');
+                const agentPart = identifierArg.substring(0, colonIndex);
+                sourceVersionId = identifierArg.substring(colonIndex + 1);
+                if (!agentPart || !sourceVersionId) {
+                    output.error('Error: Invalid argument format', 'Expected: [identifier] or [identifier]:[version-id]\nExample: guild agent fork owner/agent-name:version_xyz\n\nTo find versions:\n  guild agent versions <agent-id>');
+                    process.exit(1);
+                }
+                const resolved = await getAgentId(agentPart);
+                sourceAgentId = resolved.agentId;
+            }
+            else {
+                // No version specified — resolve agent, then find latest published
+                const resolved = await getAgentId(identifierArg);
+                sourceAgentId = resolved.agentId;
+            }
+            // Auto-resolve version if not specified
+            const client = new GuildAPIClient();
+            sourceAgentId = await resolveAgentRef(client, sourceAgentId);
+            if (!sourceVersionId) {
+                const versions = await client.get(`/agents/${sourceAgentId}/versions`);
+                const published = versions.items
+                    .filter((v) => v.status === 'PUBLISHED')
+                    .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+                if (published.length === 0) {
+                    output.error('No published versions found', `Agent ${sourceAgentId} has no published versions to fork.\n\nTo see all versions:\n  guild agent versions ${sourceAgentId}`);
+                    process.exit(1);
+                }
+                sourceVersionId = published[0].id;
             }
-            const [sourceAgentId, sourceVersionId] = parts;
             // Determine name (validate before API call for better UX)
             let agentName = options.name;
             if (!agentName) {
@@ -73,7 +101,7 @@ export function createAgentForkCommand() {
                     }
                 }
                 else {
-                    output.error('Error: Agent name required in non-interactive mode', `Provide a name:\n  guild agent fork ${sourceArg} --name my-forked-agent\n\nOr run interactively to be prompted.`);
+                    output.error('Error: Agent name required in non-interactive mode', `Provide a name:\n  guild agent fork ${identifierArg || '<identifier>'} --name my-forked-agent\n\nOr run interactively to be prompted.`);
                     process.exit(1);
                 }
             }
@@ -92,12 +120,11 @@ export function createAgentForkCommand() {
             if (dirExists) {
                 const isEmpty = await isDirectoryEmpty(targetDir);
                 if (!isEmpty) {
-                    output.error(`Error: Directory '${targetDir}' already exists and is not empty`, `Choose a different directory:\n  guild agent fork ${sourceArg} --directory ./different-path\n\nOr remove the existing directory first.`);
+                    output.error(`Error: Directory '${targetDir}' already exists and is not empty`, `Choose a different directory:\n  guild agent fork ${identifierArg || '<identifier>'} --directory ./different-path\n\nOr remove the existing directory first.`);
                     process.exit(1);
                 }
             }
-            // Now fetch source version from API (after local validations)
-            const client = new GuildAPIClient();
+            // Fetch source version from API (after local validations)
             const sourceVersion = await client.get(`/agents/${sourceAgentId}/versions/${sourceVersionId}`);
             output.progress(`✓ Fetched source version from '${sourceVersion.agent.name}' (${sourceVersionId.substring(0, 12)})`);
             // Determine description
@@ -174,8 +201,7 @@ export function createAgentForkCommand() {
                 process.exit(1);
             }
             if (formattedError.code === ErrorCodes.NOT_FOUND) {
-                const [sourceAgentId] = sourceArg.split(':');
-                output.error(`Error: Version not found: ${sourceArg}`, `Check available versions:\n  guild agent versions ${sourceAgentId}`);
+                output.error(`Error: Agent or version not found: ${identifierArg || '<identifier>'}`, `Check available versions:\n  guild agent versions <agent-id>`);
                 process.exit(1);
             }
             if (formattedError.code === ErrorCodes.CONN_REFUSED) {

package/dist/commands/agent/get.js

@@ -3,7 +3,7 @@
 import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { getAuthToken } from '../../lib/auth.js';
-import { getAgentId } from '../../lib/agent-helpers.js';
+import { getAgentId, resolveAgentRef } from '../../lib/agent-helpers.js';
 import { handleAxiosError } from '../../lib/errors.js';
 import { createOutputWriter } from '../../lib/output.js';
 export function createAgentGetCommand() {
@@ -22,7 +22,8 @@ export function createAgentGetCommand() {
             // Get agent ID from argument or guild.json
             const { agentId } = await getAgentId(idArg);
             const client = new GuildAPIClient();
-            const response = await client.get(`/agents/${agentId}`);
+            const resolvedId = await resolveAgentRef(client, agentId);
+            const response = await client.get(`/agents/${resolvedId}`);
             output.data(response);
         }
         catch (error) {

package/dist/commands/agent/grep.js

@@ -5,12 +5,14 @@ import { GuildAPIClient } from '../../lib/api-client.js';
 import { getAuthToken } from '../../lib/auth.js';
 import { createOutputWriter } from '../../lib/output.js';
 import { handleAxiosError } from '../../lib/errors.js';
+import { loadLocalConfig } from '../../lib/guild-config.js';
 export function createAgentGrepCommand() {
     const cmd = new Command('grep');
     cmd
         .description('Search agent files for a matching pattern')
         .argument('[pattern]', 'JavaScript regex for which to search: all lines matching this pattern will be printed')
-        .option('--published', 'Only search published agents')
+        .option('--all', 'Search all agents (default: current agent only)')
+        .option('--published', 'Only search published agents (requires --all)')
         .action(grep);
     return cmd;
 }
@@ -36,36 +38,11 @@ async function grep(patternArg, options) {
             process.exit(1);
         }
         const client = new GuildAPIClient();
-        let offset = 0;
-        while (true) {
-            const params = new URLSearchParams();
-            params.append('offset', `${offset}`);
-            params.append('limit', `${BATCH_SIZE}`);
-            if (options.published) {
-                params.append('published_only', 'true');
-            }
-            const response = await client.get(`/agents?${params.toString()}`);
-            await Promise.all(response.items.map(async (agent) => {
-                let files = [];
-                try {
-                    files = await client.get(`/agents/${agent.id}/code`);
-                }
-                catch (ex) {
-                    const formattedError = handleAxiosError(ex);
-                    output.error(`${agent.owner?.name}/${agent.name}: ${formattedError.details}`);
-                    return;
-                }
-                for (const { path, content } of files) {
-                    content.split('\n').forEach((line, lineNumber) => {
-                        if (patternRE.test(line)) {
-                            output.progress(`${agent.owner?.name}/${agent.name}/${path}:${lineNumber + 1}:${line}`);
-                        }
-                    });
-                }
-            }));
-            offset += response.pagination.limit;
-            if (!response.pagination.has_more)
-                break;
+        if (options.all) {
+            await grepAllAgents(client, patternRE, options.published, output);
+        }
+        else {
+            await grepCurrentAgent(client, patternRE, output);
         }
     }
     catch (error) {
@@ -74,4 +51,57 @@ async function grep(patternArg, options) {
         process.exit(1);
     }
 }
+function searchFiles(files, patternRE, prefix, output) {
+    for (const { path, content } of files) {
+        content.split('\n').forEach((line, lineNumber) => {
+            if (patternRE.test(line)) {
+                output.progress(`${prefix}${path}:${lineNumber + 1}:${line}`);
+            }
+        });
+    }
+}
+async function grepCurrentAgent(client, patternRE, output) {
+    const config = await loadLocalConfig();
+    if (!config?.agent_id) {
+        output.error('Not in an agent directory.', 'Either run from an agent directory with guild.json:\n  cd <agent-directory>\n  guild agent grep <pattern>\n\nOr search all agents:\n  guild agent grep <pattern> --all');
+        process.exit(1);
+    }
+    let files = [];
+    try {
+        files = await client.get(`/agents/${config.agent_id}/code`);
+    }
+    catch (ex) {
+        const formattedError = handleAxiosError(ex);
+        output.error(`Failed to fetch agent code: ${formattedError.details}`);
+        process.exit(1);
+    }
+    searchFiles(files, patternRE, '', output);
+}
+async function grepAllAgents(client, patternRE, publishedOnly, output) {
+    let offset = 0;
+    while (true) {
+        const params = new URLSearchParams();
+        params.append('offset', `${offset}`);
+        params.append('limit', `${BATCH_SIZE}`);
+        if (publishedOnly) {
+            params.append('published_only', 'true');
+        }
+        const response = await client.get(`/agents?${params.toString()}`);
+        await Promise.all(response.items.map(async (agent) => {
+            let files = [];
+            try {
+                files = await client.get(`/agents/${agent.id}/code`);
+            }
+            catch (ex) {
+                const formattedError = handleAxiosError(ex);
+                output.error(`${agent.owner?.name}/${agent.name}: ${formattedError.details}`);
+                return;
+            }
+            searchFiles(files, patternRE, `${agent.owner?.name}/${agent.name}/`, output);
+        }));
+        offset += response.pagination.limit;
+        if (!response.pagination.has_more)
+            break;
+    }
+}
 //# sourceMappingURL=grep.js.map

package/dist/commands/agent/init.js

@@ -79,7 +79,7 @@ export function createAgentInitCommand() {
         .option('--name <name>', 'Agent name')
         .option('--template <template>', 'Agent template (LLM, AUTO_MANAGED_STATE, BLANK)')
         .option('--fork <agent-id>', 'Fork from existing agent')
-        .option('--owner <owner-id>', 'Owner account (user or organization ID)')
+        .option('--owner <owner>', 'Owner (name or ID)')
         .option('--directory <path>', 'Directory to initialize (created if needed)')
         .option('--force', 'Overwrite existing guild.json', false)
         .action(async (options) => {

package/dist/commands/agent/publish.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
-import { getAgentId } from '../../lib/agent-helpers.js';
+import { getAgentId, resolveAgentRef } from '../../lib/agent-helpers.js';
 import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
 import { pollUntilComplete } from '../../lib/polling.js';
 import { createOutputWriter } from '../../lib/output.js';
@@ -18,8 +18,9 @@ export function createAgentPublishCommand() {
             const client = new GuildAPIClient();
             // Resolve agent ID
             const { agentId, config } = await getAgentId(agentIdArg);
+            const resolvedId = await resolveAgentRef(client, agentId);
             // Fetch all versions
-            const response = await client.get(`/agents/${agentId}/versions`);
+            const response = await client.get(`/agents/${resolvedId}/versions`);
             // Find latest DRAFT version
             const draftVersions = response.items
                 .filter((v) => v.status === 'DRAFT')

package/dist/commands/agent/pull.js

@@ -3,6 +3,7 @@
 import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
+import { getOutputMode } from '../../lib/output-mode.js';
 import { createOutputWriter } from '../../lib/output.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
@@ -90,10 +91,12 @@ export function createAgentPullCommand() {
                 if (errMessage.includes('no tracking information') ||
                     errMessage.includes("couldn't find remote ref")) {
                     output.progress('✓ Already up to date (no remote branch yet)');
-                    output.data({
-                        success: true,
-                        message: 'Already up to date (no remote branch yet)',
-                    });
+                    if (getOutputMode() === 'json') {
+                        output.data({
+                            success: true,
+                            message: 'Already up to date (no remote branch yet)',
+                        });
+                    }
                     return;
                 }
                 // Unknown git error
@@ -109,22 +112,28 @@ export function createAgentPullCommand() {
                     // Truly up to date — git pull + version match
                     if (!gitPulledNewCommits) {
                         output.progress('✓ Already up to date');
-                        output.data({ success: true, message: 'Already up to date' });
                     }
-                    else {
-                        output.data({ success: true, message: 'Pulled remote changes' });
+                    if (getOutputMode() === 'json') {
+                        output.data({
+                            success: true,
+                            message: gitPulledNewCommits
+                                ? 'Pulled remote changes'
+                                : 'Already up to date',
+                        });
                     }
                 }
                 else if (latest.sha && latest.sha !== localHead) {
                     // SHA mismatch — warn user
                     output.progress(`⚠ Remote has a newer version (${latest.sha.slice(0, 7)}) not on this branch`);
                     output.progress('  Try: git fetch origin && git log --oneline origin/main');
-                    output.data({
-                        success: true,
-                        message: 'SHA mismatch with latest version',
-                        latest_sha: latest.sha,
-                        local_sha: localHead,
-                    });
+                    if (getOutputMode() === 'json') {
+                        output.data({
+                            success: true,
+                            message: 'SHA mismatch with latest version',
+                            latest_sha: latest.sha,
+                            local_sha: localHead,
+                        });
+                    }
                 }
                 else {
                     // Ephemeral version — download from API
@@ -142,21 +151,27 @@ export function createAgentPullCommand() {
                         await fs.writeFile(filePath, file.content, 'utf-8');
                     }
                     output.progress(`✓ Downloaded ${files.length} files from latest draft version`);
-                    output.data({
-                        success: true,
-                        message: `Downloaded ${files.length} files from draft version`,
-                        files_updated: files.length,
-                    });
+                    if (getOutputMode() === 'json') {
+                        output.data({
+                            success: true,
+                            message: `Downloaded ${files.length} files from draft version`,
+                            files_updated: files.length,
+                        });
+                    }
                 }
             }
             else {
                 // No versions exist yet — just report git pull result
                 if (!gitPulledNewCommits) {
                     output.progress('✓ Already up to date');
-                    output.data({ success: true, message: 'Already up to date' });
                 }
-                else {
-                    output.data({ success: true, message: 'Pulled remote changes' });
+                if (getOutputMode() === 'json') {
+                    output.data({
+                        success: true,
+                        message: gitPulledNewCommits
+                            ? 'Pulled remote changes'
+                            : 'Already up to date',
+                    });
                 }
             }
         }

package/dist/commands/agent/revalidate.js

@@ -4,7 +4,7 @@ import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { getGuildcoreUrl } from '../../lib/config.js';
 import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
-import { getAgentId } from '../../lib/agent-helpers.js';
+import { getAgentId, resolveAgentRef } from '../../lib/agent-helpers.js';
 import { createOutputWriter } from '../../lib/output.js';
 export function createAgentRevalidateCommand() {
     const cmd = new Command('revalidate');
@@ -19,10 +19,11 @@ export function createAgentRevalidateCommand() {
         const baseUrl = getGuildcoreUrl();
         const client = new GuildAPIClient({ baseUrl });
         try {
+            const resolvedId = await resolveAgentRef(client, agentId);
             let versionId = versionIdArg;
             // If no version ID provided, get the latest version
             if (!versionId) {
-                const versions = await client.get(`/agents/${agentId}/versions?limit=1&offset=0`);
+                const versions = await client.get(`/agents/${resolvedId}/versions?limit=1&offset=0`);
                 if (!versions.items || versions.items.length === 0) {
                     output.error('No versions found for this agent.', `The agent may still be initializing. Check status:\n  guild agent get ${agentId}`);
                     process.exit(1);
@@ -30,7 +31,7 @@ export function createAgentRevalidateCommand() {
                 versionId = versions.items[0].id;
             }
             // Revalidate the version
-            const result = await client.post(`/agents/${agentId}/versions/${versionId}/revalidate`);
+            const result = await client.post(`/agents/${resolvedId}/versions/${versionId}/revalidate`);
             output.data(result);
         }
         catch (error) {

package/dist/commands/agent/save.js

@@ -13,9 +13,9 @@ import { pollUntilComplete } from '../../lib/polling.js';
 export function createAgentSaveCommand() {
     const cmd = new Command('save');
     cmd
-        .description('Push committed changes to Guild and create a version')
+        .description('Commit, push, and create a new agent version')
         .option('-A, --all', 'Stage all changes and commit before pushing', false)
-        .option('--message <text>', 'Commit message (required with --all)')
+        .option('-m, --message <text>', 'Commit message (required with --all)')
         .option('--wait', 'Wait for validation to complete before returning', false)
         .option('--publish', 'Publish after validation passes (implies --wait)', false)
         .option('--bump [level]', 'Bump package.json version before saving (patch, or minor/major)', 'patch')

package/dist/commands/agent/search.js

@@ -15,10 +15,10 @@ const SORT_MAP = {
 export function createAgentSearchCommand() {
     const cmd = new Command('search');
     cmd
-        .description('Search published agents')
+        .description('Search agents')
         .argument('<query>', 'Search query')
         .option('--sort <field>', 'Sort by: updated, newest, name, popular (default: updated)', 'updated')
-        .option('--all', 'Include unpublished agents')
+        .option('--published', 'Only show published agents')
         .option('--limit <number>', 'Number of results to return', '20')
         .option('--offset <number>', 'Offset for pagination', '0')
         .action(async (query, options) => {
@@ -34,7 +34,7 @@ export function createAgentSearchCommand() {
             params.append('search', query);
             params.append('limit', options.limit);
             params.append('offset', options.offset);
-            if (!options.all) {
+            if (options.published) {
                 params.append('published_only', 'true');
             }
             const sortField = SORT_MAP[options.sort];

package/dist/commands/agent/tags/add.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { Command } from 'commander';
 import { GuildAPIClient } from '../../../lib/api-client.js';
-import { getAgentId } from '../../../lib/agent-helpers.js';
+import { getAgentId, resolveAgentRef } from '../../../lib/agent-helpers.js';
 import { handleAxiosError, ErrorCodes } from '../../../lib/errors.js';
 import { createOutputWriter } from '../../../lib/output.js';
 export function createAgentTagsAddCommand() {
@@ -34,17 +34,18 @@ export function createAgentTagsAddCommand() {
             }
             // Now resolve agent ID properly
             const { agentId, config } = await getAgentId(agentIdArg);
+            const resolvedId = await resolveAgentRef(client, agentId);
             if (tagsToAdd.length === 0) {
                 output.error('At least one tag is required.', 'Usage: guild agent tags add [agent-id] <tag...>');
                 process.exit(1);
             }
             // Fetch current tags
-            const response = await client.get(`/agents/${agentId}/tags`);
+            const response = await client.get(`/agents/${resolvedId}/tags`);
             const currentTags = response.names;
             // Add new tags (deduplicate)
             const updatedTags = Array.from(new Set([...currentTags, ...tagsToAdd]));
             // Update tags
-            await client.post(`/agents/${agentId}/tags`, { names: updatedTags });
+            await client.post(`/agents/${resolvedId}/tags`, { names: updatedTags });
             const agentName = config?.name || `agent ${agentId}`;
             const label = `${agentName}${config ? '' : ` (${agentId})`}`;
             output.success(`Updated tags for agent: ${label}`);