@guildai/cli 0.5.9 → 0.5.11

package/README.md

@@ -210,8 +210,35 @@ guild version                           # Show version info
 ### Coding Assistant Skills
 
 ```bash
-guild setup                             # Install Guild skills for coding assistants
+guild setup                             # Install skills + configure MCP server
 guild setup --claude-md                 # Also create a CLAUDE.md template
+guild setup --no-mcp                    # Install skills only, skip MCP configuration
+guild mcp                               # Start MCP server (used by Claude Code, etc.)
+```
+
+### MCP Server
+
+The CLI includes an [MCP](https://modelcontextprotocol.io/) server that exposes Guild's API to AI coding assistants like Claude Code.
+
+**Setup:**
+
+```bash
+guild setup
+```
+
+This installs Claude Code skills and adds a `guild` entry to `.mcp.json` in your project. Claude Code (and other MCP-compatible tools) will automatically connect when they detect it.
+
+**What it provides:**
+
+- 24 tools: workspaces, agents, sessions, triggers, contexts, credentials
+- 2 resources: current workspace info and installed agents
+- All tools use your `guild auth` credentials automatically
+
+**Manual start (for debugging):**
+
+```bash
+guild mcp
+guild mcp --debug    # Verbose logging to stderr
 ```
 
 ## Configuration

package/dist/commands/agent/init.js

@@ -34,18 +34,30 @@ function slugify(text) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+const NAME_RULES = 'Lowercase letters, digits, hyphens, and underscores only (1-100 characters)';
+function isValidAgentName(name) {
+    return name.length >= 1 && name.length <= 100 && /^[a-z0-9\-_.]+$/.test(name);
+}
 async function promptForName(defaultName) {
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
     });
-    return new Promise((resolve) => {
+    const ask = () => new Promise((resolve) => {
         rl.question(`Agent name [${defaultName}]: `, (answer) => {
-            rl.close();
             const trimmed = answer.trim();
-            resolve(trimmed || defaultName);
+            const name = trimmed || defaultName;
+            if (!isValidAgentName(name)) {
+                console.error(`Invalid name "${name}": ${NAME_RULES}`);
+                resolve(ask());
+            }
+            else {
+                rl.close();
+                resolve(name);
+            }
         });
     });
+    return ask();
 }
 async function promptForTemplate() {
     const { template } = await inquirer.prompt([
@@ -120,6 +132,15 @@ export function createAgentInitCommand() {
                     process.exit(1);
                 }
             }
+            // Validate name (catches --name flag and non-interactive paths)
+            if (!isValidAgentName(agentName)) {
+                console.error(`Error: Invalid agent name "${agentName}"`);
+                console.error('');
+                console.error(`Agent names must use ${NAME_RULES}`);
+                console.error('');
+                console.error('Examples: my-agent, my_agent');
+                process.exit(1);
+            }
             // Determine template: use --template option, prompt if interactive, or error
             let template = options.template;
             if (!template) {

package/dist/commands/container/destroy.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerDestroyCommand(): Command;
+//# sourceMappingURL=destroy.d.ts.map

package/dist/commands/container/destroy.js

@@ -0,0 +1,48 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { getOutputMode } from '../../lib/output-mode.js';
+import { createOutputWriter } from '../../lib/output.js';
+export function createContainerDestroyCommand() {
+    const cmd = new Command('destroy');
+    cmd
+        .description('Destroy a running container')
+        .argument('<container-id>', 'Container ID')
+        .action(async (containerId) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const response = await client.post(`/containers/${containerId}/destroy`, {});
+            if (getOutputMode() === 'json') {
+                console.log(JSON.stringify(response, null, 2));
+            }
+            else {
+                if (response.status === 'SUCCESS') {
+                    output.success(`Container ${containerId} destroyed`);
+                }
+                else if (response.status === 'ERROR') {
+                    output.error(`Failed to destroy container: ${response.error || 'unknown error'}`);
+                    process.exit(1);
+                }
+                else {
+                    output.progress(`Container destruction ${response.status.toLowerCase()}...`);
+                }
+            }
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to destroy container: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=destroy.js.map

package/dist/commands/container/events.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerEventsCommand(): Command;
+//# sourceMappingURL=events.d.ts.map

package/dist/commands/container/events.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { getOutputMode } from '../../lib/output-mode.js';
+import { createOutputWriter, formatContainerEventTable } from '../../lib/output.js';
+export function createContainerEventsCommand() {
+    const cmd = new Command('events');
+    cmd
+        .description('List events for a container')
+        .argument('<container-id>', 'Container ID')
+        .option('--limit <number>', 'Number of results to return', '20')
+        .option('--offset <number>', 'Offset for pagination', '0')
+        .action(async (containerId, options) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const params = new URLSearchParams();
+            params.append('limit', options.limit);
+            params.append('offset', options.offset);
+            const response = await client.get(`/containers/${containerId}/events?${params.toString()}`);
+            if (getOutputMode() === 'json') {
+                console.log(JSON.stringify(response, null, 2));
+            }
+            else {
+                formatContainerEventTable(response.items, response.pagination);
+            }
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to list container events: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=events.js.map

package/dist/commands/container/exec.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerExecCommand(): Command;
+//# sourceMappingURL=exec.d.ts.map

package/dist/commands/container/exec.js

@@ -0,0 +1,64 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { getOutputMode } from '../../lib/output-mode.js';
+import { createOutputWriter } from '../../lib/output.js';
+export function createContainerExecCommand() {
+    const cmd = new Command('exec');
+    cmd
+        .description('Execute a command in a running container')
+        .argument('<container-id>', 'Container ID')
+        .argument('<command>', 'Command to execute')
+        .action(async (containerId, command) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const response = await client.post(`/containers/${containerId}/command`, { command });
+            if (getOutputMode() === 'json') {
+                console.log(JSON.stringify(response, null, 2));
+            }
+            else {
+                // Display return code
+                if (response.return_code !== null) {
+                    const codeColor = response.return_code === 0 ? chalk.green : chalk.red;
+                    console.error(chalk.dim('Return code:'), codeColor(String(response.return_code)));
+                }
+                // Display stdout
+                if (response.stdout) {
+                    console.log(response.stdout);
+                }
+                // Display stderr
+                if (response.stderr) {
+                    console.error(chalk.red(response.stderr));
+                }
+                // Display error from event
+                if (response.status === 'ERROR' && response.error) {
+                    console.error(chalk.red(`Error: ${response.error}`));
+                }
+            }
+            // Exit with the command's return code if available
+            if (response.return_code !== null && response.return_code !== 0) {
+                process.exit(response.return_code);
+            }
+            if (response.status === 'ERROR') {
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to execute command: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=exec.js.map

package/dist/commands/container/get.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerGetCommand(): Command;
+//# sourceMappingURL=get.d.ts.map

package/dist/commands/container/get.js

@@ -0,0 +1,33 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { createOutputWriter } from '../../lib/output.js';
+export function createContainerGetCommand() {
+    const cmd = new Command('get');
+    cmd
+        .description('Get container details')
+        .argument('<container-id>', 'Container ID')
+        .action(async (containerId) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const response = await client.get(`/containers/${containerId}`);
+            output.data(response);
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to get container: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=get.js.map

package/dist/commands/container/list.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerListCommand(): Command;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/container/list.js

@@ -0,0 +1,48 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { getOutputMode } from '../../lib/output-mode.js';
+import { createOutputWriter, formatContainerTable } from '../../lib/output.js';
+export function createContainerListCommand() {
+    const cmd = new Command('list');
+    cmd
+        .description('List containers for an account')
+        .requiredOption('--account <id-or-name>', 'Account ID or name')
+        .option('--status <status>', 'Filter by status: STARTING, RUNNING, ERRORED, DESTROYED')
+        .option('--limit <number>', 'Number of results to return', '20')
+        .option('--offset <number>', 'Offset for pagination', '0')
+        .action(async (options) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const params = new URLSearchParams();
+            params.append('limit', options.limit);
+            params.append('offset', options.offset);
+            if (options.status) {
+                params.append('statuses', options.status.toUpperCase());
+            }
+            const response = await client.get(`/accounts/${options.account}/containers?${params.toString()}`);
+            if (getOutputMode() === 'json') {
+                console.log(JSON.stringify(response, null, 2));
+            }
+            else {
+                formatContainerTable(response.items, response.pagination);
+            }
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to list containers: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/container-image/create.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerImageCreateCommand(): Command;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/container-image/create.js

@@ -0,0 +1,41 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { createOutputWriter } from '../../lib/output.js';
+export function createContainerImageCreateCommand() {
+    const cmd = new Command('create');
+    cmd
+        .description('Create a container image')
+        .requiredOption('--account <id-or-name>', 'Account or organization ID or name')
+        .requiredOption('--name <name>', 'Image name (1-100 characters)')
+        .requiredOption('--image <image>', 'Container image path (e.g. registry.example.com/org/image)')
+        .requiredOption('--tag <tag>', 'Image tag (e.g. latest)')
+        .action(async (opts) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const response = await client.post('/container-images', {
+                name: opts.name,
+                image_name: opts.image,
+                tag: opts.tag,
+                owner_id_or_name: opts.account,
+            });
+            output.data(response);
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to create container image: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=create.js.map

package/dist/commands/container-image/get.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerImageGetCommand(): Command;
+//# sourceMappingURL=get.d.ts.map

package/dist/commands/container-image/get.js

@@ -0,0 +1,33 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { createOutputWriter } from '../../lib/output.js';
+export function createContainerImageGetCommand() {
+    const cmd = new Command('get');
+    cmd
+        .description('Get container image details')
+        .argument('<image-id-or-name>', 'Container image ID or name (owner~name)')
+        .action(async (imageIdOrName) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const response = await client.get(`/container-images/${imageIdOrName}`);
+            output.data(response);
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to get container image: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=get.js.map

package/dist/commands/container-image/list.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createContainerImageListCommand(): Command;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/container-image/list.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { getOutputMode } from '../../lib/output-mode.js';
+import { createOutputWriter, formatContainerImageTable } from '../../lib/output.js';
+export function createContainerImageListCommand() {
+    const cmd = new Command('list');
+    cmd
+        .description('List container images for an account')
+        .requiredOption('--account <id-or-name>', 'Account ID or name')
+        .option('--limit <number>', 'Number of results to return', '20')
+        .option('--offset <number>', 'Offset for pagination', '0')
+        .action(async (options) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const params = new URLSearchParams();
+            params.append('limit', options.limit);
+            params.append('offset', options.offset);
+            const response = await client.get(`/accounts/${options.account}/container-images?${params.toString()}`);
+            if (getOutputMode() === 'json') {
+                console.log(JSON.stringify(response, null, 2));
+            }
+            else {
+                formatContainerImageTable(response.items, response.pagination);
+            }
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to list container images: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/job/get.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createJobGetCommand(): Command;
+//# sourceMappingURL=get.d.ts.map

package/dist/commands/job/get.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { getOutputMode } from '../../lib/output-mode.js';
+import { createOutputWriter, formatJobStepTable } from '../../lib/output.js';
+export function createJobGetCommand() {
+    const cmd = new Command('get');
+    cmd
+        .description('Get job details and steps')
+        .argument('<job-id>', 'Job ID')
+        .action(async (jobId) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const [job, stepsResponse] = await Promise.all([
+                client.get(`/jobs/${jobId}`),
+                client.get(`/jobs/${jobId}/steps`),
+            ]);
+            if (getOutputMode() === 'json') {
+                console.log(JSON.stringify({ ...job, steps: stepsResponse.steps }, null, 2));
+            }
+            else {
+                output.data(job);
+                console.log();
+                formatJobStepTable(stepsResponse.steps);
+            }
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to get job: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=get.js.map

package/dist/commands/job/step-get.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createJobStepGetCommand(): Command;
+//# sourceMappingURL=step-get.d.ts.map

package/dist/commands/job/step-get.js

@@ -0,0 +1,40 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { Command } from 'commander';
+import { GuildAPIClient } from '../../lib/api-client.js';
+import { getAuthToken } from '../../lib/auth.js';
+import { handleAxiosError } from '../../lib/errors.js';
+import { createOutputWriter } from '../../lib/output.js';
+export function createJobStepGetCommand() {
+    const cmd = new Command('step-get');
+    cmd
+        .description('Get details of a step in a job')
+        .argument('<job-id>', 'Job ID')
+        .argument('<step-name>', 'Step name')
+        .action(async (jobId, stepName) => {
+        const output = createOutputWriter();
+        try {
+            const token = await getAuthToken();
+            if (!token) {
+                output.error('Not authenticated. Run: guild auth login');
+                process.exit(1);
+            }
+            const client = new GuildAPIClient();
+            const stepsResponse = await client.get(`/jobs/${jobId}/steps`);
+            const step = stepsResponse.steps.find((s) => s.name === stepName);
+            if (!step) {
+                const available = stepsResponse.steps.map((s) => s.name).join(', ');
+                output.error(`Step "${stepName}" not found. Available steps: ${available || 'none'}`);
+                process.exit(1);
+            }
+            output.data(step);
+        }
+        catch (error) {
+            const formattedError = handleAxiosError(error);
+            output.error(`Failed to get job step: ${formattedError.details}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=step-get.js.map

package/dist/commands/setup.js

@@ -60,8 +60,8 @@ async function setupMcp(options) {
         const content = await fs.readFile(mcpPath, 'utf-8');
         existing = JSON.parse(content);
         if (existing.mcpServers && 'guild' in existing.mcpServers && !options.force) {
-            output.progress('Guild MCP server already configured in .mcp.json');
-            return;
+            output.progress('.mcp.json already has Guild server (use --force to overwrite)');
+            return 'skipped';
         }
     }
     const updated = {
@@ -78,6 +78,7 @@ async function setupMcp(options) {
     else {
         output.success('Created .mcp.json with Guild MCP server');
     }
+    return 'created';
 }
 async function setup(options) {
     const output = createOutputWriter();
@@ -116,7 +117,13 @@ async function setup(options) {
     }
     // Handle --mcp flag
     if (options.mcp) {
-        await setupMcp({ force: options.force });
+        const result = await setupMcp({ force: options.force });
+        if (result === 'created') {
+            filesCreated++;
+        }
+        else {
+            filesSkipped++;
+        }
     }
     // Handle CLAUDE.md template
     if (options.claudeMd) {
@@ -155,7 +162,7 @@ export function createSetupCommand() {
         .description('Set up Guild CLI skills for coding assistants (Claude Code, etc.)')
         .option('--force', 'Overwrite existing skill files', false)
         .option('--claude-md', 'Also create a CLAUDE.md template in the project root', false)
-        .option('--mcp', 'Configure Guild MCP server in .mcp.json', false)
+        .option('--no-mcp', 'Skip MCP server configuration')
         .action(async (options) => {
         await setup(options);
     });

package/dist/commands/trigger/create.js

@@ -24,6 +24,7 @@ export function createTriggerCreateCommand() {
         .option('--time <time>', 'Time of day in HH:MM format')
         .option('--days-of-week <days>', 'Days of week (comma-separated: MONDAY,TUESDAY,...)')
         .option('--days-of-month <days>', 'Days of month (comma-separated: 1,15,-1)')
+        .option('--minutes-of-hour <minutes>', 'Minutes of hour, comma-separated (0-59)')
         .option('--input <json>', 'Agent input as JSON object')
         .action(async (options) => {
         const output = createOutputWriter();
@@ -130,6 +131,9 @@ export function createTriggerCreateCommand() {
                 if (options.daysOfMonth) {
                     body.days_of_month = options.daysOfMonth;
                 }
+                if (options.minutesOfHour) {
+                    body.minutes_of_hour = options.minutesOfHour;
+                }
             }
             const response = await client.post(`/workspaces/${workspaceId}/triggers`, body);
             output.data(response);