@guildai/cli 0.5.1 → 0.5.3

package/README.md

@@ -58,17 +58,23 @@ guild auth status   # Check authentication status
 
 ```bash
 guild agent init --name my-agent        # Initialize a new agent
+guild agent clone <agent-id>            # Clone agent locally
 guild agent save                        # Push commits and create a version
 guild agent save -A --message "..."    # Stage+commit+push in one step
-guild agent versions                    # List versions
-guild agent publish                     # Publish latest draft version
-guild agent unpublish                   # Unpublish latest published version
-guild agent test                        # Test agent
-guild agent chat                        # Chat with agent in current directory
-guild agent get <agent-id>              # Get agent details
-guild agent code <agent-id>             # Fetch latest published code
-guild agent clone <agent-id>            # Clone agent locally
+guild agent pull                        # Pull remote changes
+guild agent test                        # Test agent interactively
+guild agent test --ephemeral            # Test unsaved changes
+guild agent chat "message"              # Send a single message
+guild agent get [agent-id]              # Get agent details
+guild agent versions [agent-id]         # List versions
+guild agent code [agent-id]             # View latest published source
 guild agent list                        # List all agents
+guild agent grep <pattern>              # Search agent source code
+guild agent publish                     # Publish latest draft version
+guild agent unpublish                   # Remove from catalog
+guild agent revalidate                  # Re-run validation
+guild agent update                      # Update agent metadata
+guild agent owners                      # List accounts that can own agents
 guild agent tags list                   # List tags
 guild agent tags add <tag...>           # Add tags
 guild agent tags remove <tag...>        # Remove tags

package/dist/commands/agent/pull.js

@@ -45,6 +45,7 @@ export function createAgentPullCommand() {
             const { stdout: branchName } = await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
             const currentBranch = branchName.trim();
             // Pull remote changes with rebase
+            let gitPulledNewCommits = false;
             try {
                 const { stdout: pullOutput } = await runGit(['pull', '--rebase', authenticatedUrl, currentBranch], { cwd });
                 // Update remote-tracking ref so git status stays consistent
@@ -57,23 +58,21 @@ export function createAgentPullCommand() {
                 if (pullOutput.includes('Already up to date') ||
                     pullOutput.includes('Current branch') // "Current branch X is up to date."
                 ) {
-                    output.progress('✓ Already up to date');
-                    output.data({ success: true, message: 'Already up to date' });
+                    // Don't report yet — version check below may have more to say
                 }
                 else {
+                    gitPulledNewCommits = true;
                     // Count commits pulled
                     const updateMatch = pullOutput.match(/Updating\s+[a-f0-9]+\.\.[a-f0-9]+/);
                     const fastForward = pullOutput.includes('Fast-forward');
                     let message = 'Pulled remote changes';
                     if (fastForward || updateMatch) {
-                        // Try to count files changed from pull output
                         const filesMatch = pullOutput.match(/(\d+)\s+files?\s+changed/);
                         if (filesMatch) {
                             message = `Pulled remote changes (${filesMatch[1]} files changed)`;
                         }
                     }
                     output.progress(`✓ ${message}`);
-                    output.data({ success: true, message });
                 }
             }
             catch (pullError) {
@@ -99,6 +98,66 @@ export function createAgentPullCommand() {
                 // Unknown git error
                 throw pullError;
             }
+            // Version check: compare local state against backend
+            const versions = await client.get(`/agents/${guildConfig.agent_id}/versions?limit=1`);
+            if (versions.items.length > 0) {
+                const latest = versions.items[0];
+                const { stdout: headSha } = await runGit(['rev-parse', 'HEAD'], { cwd });
+                const localHead = headSha.trim();
+                if (latest.sha && latest.sha === localHead) {
+                    // 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' });
+                    }
+                }
+                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,
+                    });
+                }
+                else {
+                    // Ephemeral version — download from API
+                    output.progress('Remote has unpublished changes from the web editor');
+                    // Check for local uncommitted changes
+                    const { stdout: status } = await runGit(['status', '--porcelain'], { cwd });
+                    if (status.trim()) {
+                        output.error('Cannot download remote changes — you have uncommitted local changes', 'Commit or stash your changes first, then run guild agent pull again.');
+                        process.exit(1);
+                    }
+                    const files = await client.get(`/agents/${guildConfig.agent_id}/code?include_unpublished=1`);
+                    for (const file of files) {
+                        const filePath = path.join(cwd, file.path);
+                        await fs.mkdir(path.dirname(filePath), { recursive: true });
+                        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,
+                    });
+                }
+            }
+            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' });
+                }
+            }
         }
         catch (error) {
             if (error instanceof GitError) {

package/dist/commands/agent/save.js

@@ -258,7 +258,7 @@ export function createAgentSaveCommand() {
             output.progress('');
             output.progress('Version details:');
             output.progress(`  ID: ${version.id}`);
-            output.progress(`  SHA: ${version.sha.substring(0, 12)}`);
+            output.progress(`  SHA: ${version.sha ? version.sha.substring(0, 12) : '-'}`);
             output.progress(`  Status: ${version.status}`);
             if (version.published_at) {
                 output.progress(`  Published at: ${version.published_at}`);

package/dist/commands/auth/status.js

@@ -2,16 +2,33 @@
 import { Command } from 'commander';
 import { getAuthStatus } from '../../lib/auth.js';
 import { createOutputWriter } from '../../lib/output.js';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { GuildCLIError, ErrorCodes } from '../../lib/errors.js';
 export function createAuthStatusCommand() {
     const cmd = new Command('status');
     cmd.description('Check authentication status').action(async () => {
         const output = createOutputWriter();
         const { authenticated } = await getAuthStatus();
-        if (authenticated) {
-            output.success('Authenticated');
-        }
-        else {
+        if (!authenticated) {
             output.error('Not authenticated');
+            process.exit(0);
+            return;
+        }
+        // Try to fetch user profile for richer output
+        try {
+            const client = new GuildAPIClient();
+            const me = await client.get('/me');
+            output.success(`Authenticated as ${me.name} (${me.id})`);
+        }
+        catch (error) {
+            if (error instanceof GuildCLIError &&
+                error.code === ErrorCodes.AUTH_TOKEN_INVALID) {
+                output.error('Not authenticated (token expired)', 'Run: guild auth login');
+            }
+            else {
+                // Offline or other network error — fall back to simple message
+                output.success('Authenticated');
+            }
         }
         process.exit(0);
     });

package/dist/commands/chat.js

@@ -4,7 +4,7 @@ import { Box, Text, Static, render, useInput, useApp } from 'ink';
 import { Command } from 'commander';
 import { getAuthToken, showBetaGuidance } from '../lib/auth.js';
 import { GuildAPIClient } from '../lib/api-client.js';
-import { handleAxiosError, ErrorCodes, debug, retry } from '../lib/errors.js';
+import { handleAxiosError, ErrorCodes, debug, isDebugMode, retry, } from '../lib/errors.js';
 import { createSpinner, format } from '../lib/progress.js';
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
@@ -567,6 +567,18 @@ function ChatUIWithConnection({ initialPrompt, version: _version, versionId: _ve
                             ]);
                             setCurrentOperation('');
                         }
+                        else if (event.type === 'agent_console' && isDebugMode()) {
+                            // Show console logs when debug mode is enabled (matches www debug checkbox behavior)
+                            const content = typeof event.content === 'string' ? event.content : '';
+                            setMessages((prev) => [
+                                ...prev,
+                                {
+                                    key: `console-${Date.now()}-${Math.random()}`,
+                                    content: chalk.dim(`[console.${event.level}] ${content}`),
+                                    type: 'assistant',
+                                },
+                            ]);
+                        }
                         else if (event.type === 'runtime_done' &&
                             !receivedResponseSinceLastInput.current &&
                             event.content !== undefined &&

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

@@ -58,7 +58,7 @@ export function createWorkspaceAgentAddCommand() {
             // Display success
             const versionDisplay = response.agent_version.version_number
                 ? `v${response.agent_version.version_number}`
-                : response.agent_version.sha.slice(0, 7);
+                : (response.agent_version.sha?.slice(0, 7) ?? '-');
             const workspaceName = response.workspace?.name || 'workspace';
             output.success(`Added ${response.agent.full_name} to workspace "${workspaceName}"`, {
                 Agent: response.agent.full_name,

package/dist/commands/workspace/select.js

@@ -18,6 +18,16 @@ function formatWorkspaceDisplay(workspace) {
     }
     return base;
 }
+/**
+ * Match a workspace against a search argument (case-insensitive name, full_name, or exact ID).
+ */
+function matchesWorkspaceArg(w, arg) {
+    return (w.name === arg ||
+        w.name.toLowerCase() === arg.toLowerCase() ||
+        w.full_name === arg ||
+        w.full_name?.toLowerCase() === arg.toLowerCase() ||
+        w.id === arg);
+}
 export function createWorkspaceSelectCommand() {
     const cmd = new Command('select');
     cmd
@@ -27,24 +37,25 @@ export function createWorkspaceSelectCommand() {
         const output = createOutputWriter();
         try {
             const client = new GuildAPIClient();
-            // Use filter=all to get workspaces from all orgs user is a member of
-            const workspaces = await client.get('/me/workspaces?filter=all');
-            if (workspaces.items.length === 0) {
-                output.error('No workspaces found.', 'Create a workspace first:\n  guild workspace create <name>');
-                process.exit(1);
-            }
-            // If a workspace argument was provided, find and select it directly
+            // If a workspace argument was provided, use server-side search to find it
             if (workspaceArg) {
-                const workspace = workspaces.items.find((w) => w.name === workspaceArg ||
-                    w.name.toLowerCase() === workspaceArg.toLowerCase() ||
-                    w.full_name === workspaceArg ||
-                    w.full_name?.toLowerCase() === workspaceArg.toLowerCase() ||
-                    w.id === workspaceArg);
+                // Use search param to narrow results server-side, then exact-match client-side.
+                // The backend searches only the "name" column via ILIKE, so full_name (owner/name)
+                // and ID lookups may not return results. Extract just the name part for search,
+                // and if still no match, fall back to fetching the full list.
+                const searchTerm = workspaceArg.includes('/')
+                    ? workspaceArg.split('/').pop()
+                    : workspaceArg;
+                const searchResults = await client.get(`/me/workspaces?filter=all&search=${encodeURIComponent(searchTerm)}&limit=100`);
+                let workspace = searchResults.items.find((w) => matchesWorkspaceArg(w, workspaceArg));
+                // Search didn't find it (could be an ID lookup, or search term didn't match).
+                // Fall back to fetching all workspaces via pagination.
                 if (!workspace) {
-                    const available = workspaces.items
-                        .map((w) => `  - ${formatWorkspaceDisplay(w)}`)
-                        .join('\n');
-                    output.error(`Workspace "${workspaceArg}" not found.`, `Available workspaces:\n${available}`);
+                    const allWorkspaces = await client.fetchAll('/me/workspaces?filter=all');
+                    workspace = allWorkspaces.find((w) => matchesWorkspaceArg(w, workspaceArg));
+                }
+                if (!workspace) {
+                    output.error(`Workspace "${workspaceArg}" not found.`, 'Run: guild workspace list');
                     process.exit(1);
                 }
                 const target = await saveWorkspaceConfig(workspace.id, workspace.name);
@@ -56,6 +67,12 @@ export function createWorkspaceSelectCommand() {
                 }
                 return;
             }
+            // Interactive mode: fetch workspaces for selection
+            const workspaces = await client.get('/me/workspaces?filter=all');
+            if (workspaces.items.length === 0) {
+                output.error('No workspaces found.', 'Create a workspace first:\n  guild workspace create <name>');
+                process.exit(1);
+            }
             // Resolve the currently selected workspace (if any)
             const current = await getWorkspaceId();
             const currentIndex = current

package/dist/lib/api-types.d.ts

@@ -63,7 +63,7 @@ export interface WorkspaceAgent {
     };
     agent_version: {
         id: string;
-        sha: string;
+        sha: string | null;
         version_number: string | null;
     };
     workspace?: {
@@ -83,11 +83,12 @@ export interface AgentVersion {
     id: string;
     agent_id?: string;
     author_id?: string;
-    sha: string;
+    sha: string | null;
     summary: string;
     status: string;
     validation_status?: string;
     version_number?: string | null;
+    version_type?: 'COMMITTED' | 'EPHEMERAL';
     published_at?: string | null;
     created_at: string;
     updated_at?: string;
@@ -227,7 +228,7 @@ export interface TriggerWorkspaceAgent {
     };
     agent_version: {
         id: string;
-        sha: string;
+        sha: string | null;
         version_number: string | null;
     };
 }

package/dist/lib/colors.d.ts

@@ -17,4 +17,15 @@ export declare const warn: import("chalk").ChalkInstance;
  * Replaces chalk.yellow for code highlighting.
  */
 export declare const code: import("chalk").ChalkInstance;
+/**
+ * Wrap text in an OSC8 terminal hyperlink.
+ *
+ * In supported terminals (iTerm2, VS Code, Windows Terminal, etc.),
+ * the text becomes clickable. Falls back to plain text when:
+ * - Output is piped (non-TTY)
+ * - FORCE_HYPERLINK=0
+ *
+ * Set FORCE_HYPERLINK=1 to force hyperlinks even in non-TTY.
+ */
+export declare function hyperlink(text: string, url: string): string;
 //# sourceMappingURL=colors.d.ts.map

package/dist/lib/colors.js

@@ -23,4 +23,23 @@ export const warn = chalk.hex('#b8860b');
  * Replaces chalk.yellow for code highlighting.
  */
 export const code = chalk.hex('#b8860b');
+/**
+ * Wrap text in an OSC8 terminal hyperlink.
+ *
+ * In supported terminals (iTerm2, VS Code, Windows Terminal, etc.),
+ * the text becomes clickable. Falls back to plain text when:
+ * - Output is piped (non-TTY)
+ * - FORCE_HYPERLINK=0
+ *
+ * Set FORCE_HYPERLINK=1 to force hyperlinks even in non-TTY.
+ */
+export function hyperlink(text, url) {
+    const force = process.env.FORCE_HYPERLINK;
+    if (force === '0')
+        return text;
+    const supported = force === '1' || process.stderr.isTTY;
+    if (!supported)
+        return text;
+    return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}
 //# sourceMappingURL=colors.js.map

package/dist/lib/config.d.ts

@@ -38,6 +38,13 @@ export declare const IAP_SERVICE_ACCOUNT: string;
  * @returns Base URL for Guildcore API (e.g., "https://app.guild.ai/api")
  */
 export declare function getGuildcoreUrl(): string;
+/**
+ * Get the dashboard (frontend) base URL
+ *
+ * Derives the frontend URL from the guildcore API URL by stripping /api.
+ * Used to construct clickable links to dashboard pages.
+ */
+export declare function getDashboardUrl(): string;
 /**
  * Check if the given URL is an IAP-protected host
  *

package/dist/lib/config.js

@@ -96,6 +96,15 @@ export function getGuildcoreUrl() {
     // Default to production
     return DEFAULT_GUILDCORE_URL;
 }
+/**
+ * Get the dashboard (frontend) base URL
+ *
+ * Derives the frontend URL from the guildcore API URL by stripping /api.
+ * Used to construct clickable links to dashboard pages.
+ */
+export function getDashboardUrl() {
+    return getGuildcoreUrl().replace(/\/api$/, '');
+}
 /**
  * Check if the given URL is an IAP-protected host
  *

package/dist/lib/output.js

@@ -3,7 +3,8 @@ import chalk from 'chalk';
 import { Table } from 'console-table-printer';
 import { getOutputMode, isQuietMode } from './output-mode.js';
 import { createSpinner } from './progress.js';
-import { brand } from './colors.js';
+import { brand, hyperlink } from './colors.js';
+import { getDashboardUrl } from './config.js';
 /**
  * Format a relative timestamp (e.g. "2d ago", "3mo ago")
  */
@@ -57,9 +58,12 @@ export function formatAgentTable(agents, pagination) {
             { name: 'updated', title: 'UPDATED', alignment: 'left' },
         ],
     });
+    const base = getDashboardUrl();
     agents.forEach((agent) => {
+        const name = agent.full_name || agent.name;
+        const agentUrl = agent.full_name ? `${base}/agents/${agent.full_name}` : '';
         table.addRow({
-            name: agent.full_name || agent.name,
+            name: agentUrl ? hyperlink(name, agentUrl) : name,
             owner: agent.owner?.name || '',
             description: truncate(agent.description || '', 40),
             updated: agent.updated_at ? formatRelativeTime(agent.updated_at) : '',
@@ -87,7 +91,7 @@ export function formatVersionTable(versions, pagination) {
     }
     const table = new Table({
         columns: [
-            { name: 'sha', title: 'SHA', alignment: 'left' },
+            { name: 'id', title: 'ID', alignment: 'left' },
             { name: 'version', title: 'VERSION', alignment: 'left', color: 'cyan' },
             { name: 'status', title: 'STATUS', alignment: 'left' },
             { name: 'validation', title: 'VALIDATION', alignment: 'left' },
@@ -102,7 +106,7 @@ export function formatVersionTable(versions, pagination) {
                 ? chalk.red
                 : chalk.dim;
         table.addRow({
-            sha: v.sha.slice(0, 7),
+            id: v.id.substring(0, 8),
             version: v.version_number || '-',
             status: v.status,
             validation: validationColor(v.validation_status || '-'),
@@ -173,10 +177,13 @@ export function formatWorkspaceAgentTable(agents) {
             { name: 'auto_update', title: 'AUTO-UPDATE', alignment: 'left' },
         ],
     });
+    const base = getDashboardUrl();
     agents.forEach((wa) => {
+        const name = wa.agent.full_name || wa.agent.name;
+        const agentUrl = wa.agent.full_name ? `${base}/agents/${wa.agent.full_name}` : '';
         table.addRow({
-            name: wa.agent.full_name || wa.agent.name,
-            version: wa.agent_version.version_number || wa.agent_version.sha.slice(0, 7),
+            name: agentUrl ? hyperlink(name, agentUrl) : name,
+            version: wa.agent_version.version_number || wa.agent_version.id.substring(0, 8),
             auto_update: wa.should_autoupdate ? chalk.green('yes') : chalk.dim('no'),
         });
     });
@@ -236,9 +243,10 @@ export function formatSessionTable(sessions, pagination) {
             { name: 'created', title: 'CREATED', alignment: 'left' },
         ],
     });
+    const base = getDashboardUrl();
     sessions.forEach((session) => {
         table.addRow({
-            id: truncate(session.id, 8),
+            id: hyperlink(session.id, `${base}/sessions/${session.id}`),
             type: session.session_type,
             name: session.name ? truncate(session.name, 30) : '-',
             workspace: session.workspace?.name || '',
@@ -274,16 +282,21 @@ export function formatTriggerTable(triggers, pagination) {
             { name: 'created', title: 'CREATED', alignment: 'left' },
         ],
     });
+    const base = getDashboardUrl();
     triggers.forEach((trigger) => {
         const status = trigger.disabled_reason
             ? chalk.yellow('disabled')
             : trigger.deactivated_at
                 ? chalk.dim('inactive')
                 : chalk.green('active');
+        const agentName = trigger.agent?.full_name || trigger.agent?.name || '';
+        const agentUrl = trigger.agent?.full_name
+            ? `${base}/agents/${trigger.agent.full_name}`
+            : '';
         table.addRow({
-            id: truncate(trigger.id, 8),
+            id: hyperlink(trigger.id, `${base}/triggers/${trigger.id}/sessions`),
             type: trigger.type,
-            agent: trigger.agent?.full_name || trigger.agent?.name || '',
+            agent: agentUrl ? hyperlink(agentName, agentUrl) : agentName,
             status,
             created: trigger.created_at ? formatRelativeTime(trigger.created_at) : '',
         });

package/dist/lib/session-polling.js

@@ -1,4 +1,5 @@
 // Copyright (c) 2026 Guild.ai All Rights Reserved
+import { isDebugMode } from './errors.js';
 /**
  * Poll for agent response after a certain event count.
  *
@@ -30,6 +31,9 @@ export async function pollForResponse(client, sessionId, afterEventCount, maxWai
             if (event.type === 'runtime_error' && event.task && 'agent' in event.task) {
                 return JSON.stringify({ error: event.content });
             }
+            if (event.type === 'agent_console' && isDebugMode()) {
+                process.stderr.write(`[console.${event.level}] ${event.content}\n`);
+            }
         }
         if (lastAgentRuntimeDone !== null) {
             return lastAgentRuntimeDone;

package/docs/CLI_WORKFLOW.md

@@ -81,6 +81,7 @@ guild agent clone guildai/dev-assistant
 cd dev-assistant
 
 # Pull remote changes (from collaborators or web edits)
+# Also syncs unpublished changes made via the web editor
 guild agent pull
 
 # Check current version status

package/docs/getting-started.md

@@ -278,6 +278,8 @@ If others are working on the same agent, pull their changes first:
 guild agent pull
 ```
 
+This pulls git commits and also checks for unpublished changes made via the web editor. If someone edited the agent in the UI, pull downloads those files automatically.
+
 ### 2. Test locally
 
 ```bash

package/docs/output-format.md

@@ -115,3 +115,12 @@ guild agent create my-agent --quiet
 **JSON by default for data**: `agent list`, `workspace list`, etc. output JSON. The `guild chat` interface provides human-readable interaction.
 
 **Quiet mode independent**: Works with both human and JSON modes. Suppresses progress, keeps errors.
+
+## Hyperlinks
+
+Table cells for entity names and IDs are wrapped in [OSC8 terminal hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) that link to the corresponding dashboard pages. In supported terminals (iTerm2, VS Code Terminal, Windows Terminal), these cells are clickable.
+
+**Environment controls:**
+
+- `FORCE_HYPERLINK=1` — Force hyperlinks in non-TTY environments
+- `FORCE_HYPERLINK=0` — Disable hyperlinks entirely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guildai/cli",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Guild.ai CLI - Build, test, and deploy AI agents",
   "type": "module",
   "main": "dist/index.js",