@guildai/cli 0.5.3 → 0.5.4

package/README.md

@@ -2,6 +2,11 @@
 
 Command-line interface for [Guild.ai](https://guild.ai) — build, test, and deploy AI agents.
 
+## Prerequisites
+
+- **Node.js 18+** and **npm** — [nodejs.org](https://nodejs.org)
+- **A Guild account** — Guild.ai is in closed beta. Request an invitation at hello@guild.ai
+
 ## Installation
 
 ```bash
@@ -16,68 +21,126 @@ npm install -g @guildai/cli
 guild auth login
 ```
 
-Visit the displayed URL and complete authentication. Your token is stored securely in your system keyring.
+This opens your browser to complete sign-in at [app.guild.ai](https://app.guild.ai). It also configures your local npm registry so the CLI can install Guild packages.
+
+Verify:
+
+```bash
+guild auth status
+```
 
-### 2. Create an Agent
+### 2. Select a workspace
 
 ```bash
-mkdir my-agent && cd my-agent
-guild agent init --name my-agent
+guild workspace select
 ```
 
-### 3. Develop and Save
+If you have one workspace, it's selected automatically. If you have several, pick one from the list.
+
+### 3. Create an agent
 
 ```bash
-# Edit agent.ts, then commit and save
-git add . && git commit -m "Initial implementation"
-guild agent save
+mkdir hello-agent && cd hello-agent
+guild agent init --name hello-agent --template LLM
+```
 
-# Or stage+commit+push in one step
-guild agent save -A --message "Initial implementation"
+This creates the agent in the Guild backend, initializes a local git repo, and pulls starter files:
+
+```
+hello-agent/
+├── agent.ts          # Your agent code
+├── package.json      # Dependencies
+├── tsconfig.json     # TypeScript config
+├── guild.json        # Local config (managed by the CLI, don't edit)
+└── .gitignore
 ```
 
-### 4. Test Your Agent
+### 4. Edit the agent
+
+Open `agent.ts` and replace the contents:
+
+```typescript
+import { llmAgent, guildTools, userInterfaceTools } from '@guildai/agents-sdk';
+
+export default llmAgent({
+  description: 'A friendly greeting agent',
+  tools: { ...guildTools, ...userInterfaceTools },
+  systemPrompt: `You are a friendly assistant. Greet users warmly and answer their questions.`,
+  mode: 'multi-turn',
+});
+```
+
+### 5. Test it
 
 ```bash
-guild agent test
+guild agent test --ephemeral
 ```
 
-Full getting-started guide: [docs.guild.ai/cli/getting-started](https://docs.guild.ai/cli/getting-started)
+Type a message and press Enter. Press `Ctrl+C` to exit.
+
+### 6. Save and publish
+
+```bash
+guild agent save --message "First version" --wait --publish
+```
+
+- `--wait` blocks until validation passes
+- `--publish` makes the agent available in the Guild catalog
+
+## Templates
+
+| Template             | Use when                                                             |
+| -------------------- | -------------------------------------------------------------------- |
+| `LLM`                | The LLM is the logic. You write a prompt and pick tools. Start here. |
+| `AUTO_MANAGED_STATE` | You write procedural TypeScript that calls tools inline.             |
+| `BLANK`              | You want full control over the agent lifecycle.                      |
+
+## Development Loop
+
+The typical workflow: pull → edit → test → save.
+
+```bash
+guild agent pull                                    # Sync remote changes
+# ... edit agent.ts ...
+guild agent test                                    # Interactive test session
+guild agent save --message "Add Slack notifications" # Save as draft
+guild agent save --message "Ready" --wait --publish  # Save + validate + publish
+```
 
 ## Commands
 
 ### Authentication
 
 ```bash
-guild auth login    # OAuth device flow login
-guild auth logout   # Remove stored token
-guild auth status   # Check authentication status
+guild auth login                        # OAuth device flow login
+guild auth logout                       # Remove stored token
+guild auth status                       # Check authentication status
+guild auth token                        # Print auth token to stdout (for scripting)
 ```
 
 ### Agents
 
 ```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 clone <identifier>          # Clone an existing agent
 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 save --message "..."        # Save changes (creates draft version)
+guild agent save --message "..." --wait --publish  # Save + validate + publish
 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 unpublish                   # Unpublish latest published version
+guild agent test                        # Interactive test session
+guild agent test --ephemeral            # Test uncommitted changes
+guild agent chat "Hello"               # Send a single message
+guild agent get [identifier]            # Get agent details
+guild agent versions [identifier]       # List version history
+guild agent code [identifier]           # Fetch latest published code
+guild agent list                        # List all agents
+guild agent search <query>              # Search published agents
+guild agent grep <pattern>              # Search agent code files
+guild agent fork <agent-id>:<version>   # Fork an existing agent version
 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
+guild agent tags list|add|remove        # Manage agent tags
+guild agent revalidate                  # Re-run validation
 ```
 
 ### Workspaces
@@ -97,6 +160,29 @@ guild workspace context edit            # Edit context (opens editor)
 guild workspace context publish         # Publish draft context
 ```
 
+### Sessions
+
+```bash
+guild session list                      # List sessions in a workspace
+guild session get <session-id>          # Get session details
+guild session events <session-id>       # List events in a session
+guild session tasks <session-id>        # List tasks in a session
+guild session create                    # Create a new session
+guild session send <session-id>         # Send a message to a session
+```
+
+### Triggers
+
+```bash
+guild trigger list                      # List triggers in a workspace
+guild trigger get <trigger-id>          # Get trigger details
+guild trigger create                    # Create a new trigger
+guild trigger update <trigger-id>       # Update a trigger
+guild trigger activate <trigger-id>     # Activate a trigger
+guild trigger deactivate <trigger-id>   # Deactivate a trigger
+guild trigger sessions <trigger-id>     # List sessions spawned by a trigger
+```
+
 ### Chat
 
 ```bash
@@ -105,6 +191,29 @@ guild chat "your message"               # One-shot message
 guild chat --agent <agent-id>           # Chat with specific agent
 ```
 
+### Configuration
+
+```bash
+guild config list                       # Show all configuration values
+guild config get <key>                  # Get a configuration value
+guild config set <key> <value>          # Set a global configuration value
+guild config path                       # Show configuration file paths
+```
+
+### Diagnostics
+
+```bash
+guild doctor                            # Check CLI setup and diagnose issues
+guild version                           # Show version info
+```
+
+### Coding Assistant Skills
+
+```bash
+guild setup                             # Install Guild skills for coding assistants
+guild setup --claude-md                 # Also create a CLAUDE.md template
+```
+
 ## Configuration
 
 **Global config** (`~/.guild/config.json`):
@@ -134,28 +243,67 @@ OAuth tokens are stored in your system's secure credential store:
 
 ## Troubleshooting
 
-### Authentication Failed
+### "Connection refused" or "Cannot connect to server"
+
+1. Check your internet connection
+2. Run `guild doctor` to see which check is failing
+
+### "Not authenticated"
 
 ```bash
-guild auth status   # Check authentication status
-guild auth logout   # Clear token
-guild auth login    # Re-authenticate
+guild auth login
+guild auth status
 ```
 
-### Keychain Issues
+### "Workspace not found" or wrong workspace
+
+```bash
+guild workspace select
+```
+
+Or override for a single command:
+
+```bash
+GUILD_WORKSPACE_ID=<workspace-id> guild agent test
+```
+
+### "No agent ID provided and not in an agent directory"
+
+Either run from inside an agent directory (one with a `guild.json` file), or pass the agent ID explicitly:
+
+```bash
+guild agent get <agent-id>
+```
+
+### "No changes to commit"
+
+All changes are already committed. Make a code change first, then run `guild agent save` again.
+
+### Validation failures
+
+```bash
+guild agent versions --limit 1          # Check for errors
+# Fix the issue, then:
+guild agent save --message "Fix" --wait
+```
+
+### Agent test not responding
+
+1. Check your agent code compiles — look for TypeScript errors in `agent.ts`
+2. Make sure you've saved at least once: `guild agent save --message "initial"`
+3. Try a single message instead: `guild agent chat "hello"`
 
-If you see errors about keychain or credential storage:
+### Keychain issues
 
 - **macOS**: Ensure Keychain Access is working and not locked
 - **Linux**: Install and configure libsecret (e.g., `gnome-keyring`)
 - **Windows**: Check Credential Manager is accessible
 
-### Command Not Found
+### Command not found
 
 Ensure npm global bin directory is in your PATH:
 
 ```bash
-npm config get prefix
 export PATH="$(npm config get prefix)/bin:$PATH"
 ```
 
@@ -166,4 +314,4 @@ export PATH="$(npm config get prefix)/bin:$PATH"
 
 ## License
 
-Proprietary - All rights reserved.
+MIT

package/dist/commands/agent/chat.js

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import { render } from 'ink';
 import React from 'react';
 import open from 'open';
-import chalk from 'chalk';
+import { hyperlink } from '../../lib/colors.js';
 import { getAgentId, readAgentFiles } from '../../lib/agent-helpers.js';
 import { ChatApp, createSession, ensureAuthenticated } from '../chat.js';
 import { readFileSync } from 'fs';
@@ -172,10 +172,10 @@ export function createAgentChatCommand() {
                 const session = await createSession(client, options.workspace, initialPrompt, version.id);
                 if (!quiet) {
                     console.log(`✓ Agent: ${config?.name || agentId}`);
-                    console.log(`✓ Session created: ${session.id}`);
-                    if (session.session_url) {
-                        console.log(chalk.dim(`  View in dashboard: ${session.session_url}`));
-                    }
+                    const sessionLink = session.session_url
+                        ? hyperlink(session.id, session.session_url)
+                        : session.id;
+                    console.log(`✓ Session: ${sessionLink}`);
                     console.log('');
                 }
                 if (options.open && session.session_url) {

package/dist/commands/agent/save.js

@@ -17,13 +17,29 @@ export function createAgentSaveCommand() {
         .option('--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')
+        .option('--no-bump', 'Skip automatic version bump')
         .option('--json', 'Output JSON only (no progress messages)', false)
         .action(async (options) => {
         const cwd = process.cwd();
         let guildConfig = null;
         const output = createOutputWriter();
-        // With --all, a commit message is required
-        if (options.all && !options.message) {
+        // Resolve bump level: bare --bump defaults to 'patch', --no-bump skips
+        const bumpLevel = options.bump === true || options.bump === 'patch'
+            ? 'patch'
+            : options.bump === 'minor'
+                ? 'minor'
+                : options.bump === 'major'
+                    ? 'major'
+                    : options.bump === false
+                        ? null
+                        : null;
+        if (options.bump !== false && bumpLevel === null) {
+            output.error(`Invalid bump level: ${String(options.bump)}`, 'Valid levels are: patch, minor, major\n  guild agent save --bump minor');
+            process.exit(1);
+        }
+        // With --all, a commit message is required (unless bump auto-generates one)
+        if (options.all && !options.message && !bumpLevel) {
             output.error('Commit message is required with --all', 'Provide a message describing your changes:\n  guild agent save -A --message "Add new feature"');
             process.exit(1);
         }
@@ -40,6 +56,39 @@ export function createAgentSaveCommand() {
             }
             // Read guild.json
             guildConfig = JSON.parse(await fs.readFile(guildJsonPath, 'utf-8'));
+            // Handle --bump: bump package.json version before git operations
+            if (bumpLevel) {
+                const packageJsonPath = path.join(cwd, 'package.json');
+                let packageJsonContent;
+                try {
+                    packageJsonContent = await fs.readFile(packageJsonPath, 'utf-8');
+                }
+                catch {
+                    output.error('package.json not found', 'A package.json file is required in the agent directory to use --bump.');
+                    process.exit(1);
+                }
+                const packageJson = JSON.parse(packageJsonContent);
+                const currentVersion = packageJson.version || '0.0.0';
+                const parts = currentVersion.split('.').map(Number);
+                if (parts.length !== 3 || parts.some((p) => isNaN(p))) {
+                    output.error(`Cannot bump invalid version: ${currentVersion}`, 'package.json version must be in MAJOR.MINOR.PATCH format (e.g. 1.0.0)');
+                    process.exit(1);
+                }
+                const [major, minor, patch] = parts;
+                let newVersion;
+                if (bumpLevel === 'major') {
+                    newVersion = `${major + 1}.0.0`;
+                }
+                else if (bumpLevel === 'minor') {
+                    newVersion = `${major}.${minor + 1}.0`;
+                }
+                else {
+                    newVersion = `${major}.${minor}.${patch + 1}`;
+                }
+                packageJson.version = newVersion;
+                await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+                output.progress(`✓ Bumped version: ${currentVersion} → ${newVersion}`);
+            }
             // Check for uncommitted changes and unpushed commits
             const { stdout: statusOutput } = await runGit(['status', '--porcelain'], {
                 cwd,
@@ -65,12 +114,15 @@ export function createAgentSaveCommand() {
                     hasUnpushedCommits = false;
                 }
             }
-            if (options.all) {
-                // --all: stage and commit before pushing
+            // --bump implies --all (the version change needs to be committed)
+            const shouldStageAll = options.all || !!bumpLevel;
+            if (shouldStageAll) {
+                // Stage and commit before pushing
                 if (hasUncommittedChanges) {
                     await runGit(['add', '-A'], { cwd });
                     output.progress('✓ Staged changes');
-                    await runGit(['commit', '-m', options.message], { cwd });
+                    const commitMsg = options.message || (bumpLevel ? `Bump version` : '');
+                    await runGit(['commit', '-m', commitMsg], { cwd });
                     output.progress('✓ Committed locally');
                     hasUnpushedCommits = true;
                 }

package/dist/commands/agent/test.js

@@ -6,7 +6,7 @@ import { readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import open from 'open';
-import chalk from 'chalk';
+import { hyperlink } from '../../lib/colors.js';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
 import { format } from '../../lib/progress.js';
@@ -284,10 +284,10 @@ export function createAgentTestCommand() {
                     : commitSha?.substring(0, 12) || 'unknown';
                 console.log(`✓ Version: ${versionDisplay}`);
                 console.log(`✓ Workspace: ${workspaceId}`);
-                console.log(`✓ Session created: ${session.id}`);
-                if (session.session_url) {
-                    console.log(chalk.dim(`  View in dashboard: ${session.session_url}`));
-                }
+                const sessionLink = session.session_url
+                    ? hyperlink(session.id, session.session_url)
+                    : session.id;
+                console.log(`✓ Session: ${sessionLink}`);
                 console.log('');
             }
             if (options.open && session.session_url) {

package/dist/commands/chat.js

@@ -17,7 +17,7 @@ import { printResumeHint, fetchSession, fetchSessionEvents, eventsToDisplayMessa
 import { AgentInstallPrompt } from '../components/AgentInstallPrompt.js';
 import { getWorkspaceId } from '../lib/guild-config.js';
 import { ensureInteractiveStdin } from '../lib/stdin.js';
-import { brand, BRAND_COLOR, code as codeColor } from '../lib/colors.js';
+import { brand, BRAND_COLOR, code as codeColor, hyperlink } from '../lib/colors.js';
 import { SplashAnimation } from '../components/SplashAnimation.js';
 import { LOADING_TIMINGS } from '../lib/loading-messages.js';
 import { suppressScrollbackClear } from '../lib/alternate-screen.js';
@@ -222,10 +222,20 @@ function ChatUIWithConnection({ initialPrompt, version: _version, versionId: _ve
     const resumeDisplayMessages = resumeEvents
         ? eventsToDisplayMessages(resumeEvents)
         : null;
+    const sessionLinkMessage = isActive && preConnectedSession?.session_url
+        ? [
+            {
+                key: 'session-link',
+                content: chalk.dim(`Session: ${hyperlink(preConnectedSession.id, preConnectedSession.session_url)}`),
+                type: 'progress',
+            },
+        ]
+        : [];
     const [messages, setMessages] = useState(resumeDisplayMessages
         ? resumeDisplayMessages
         : isActive
             ? [
+                ...sessionLinkMessage,
                 {
                     key: 'initial',
                     content: `${brand('>')} ${initialPrompt}`,
@@ -920,6 +930,10 @@ export function createChatCommand() {
                 const client = new GuildAPIClient();
                 const session = await createSession(client, options.workspace, initialPrompt, options.agent);
                 spinner.succeed('Connected');
+                if (session.session_url) {
+                    const sessionLink = hyperlink(session.id, session.session_url);
+                    console.error(chalk.dim(`Session: ${sessionLink}`));
+                }
                 console.error('');
                 // Non-interactive mode: send message, wait for response, output JSON
                 // Poll for messages until we get an agent MESSAGE response

package/dist/commands/config/set.js

@@ -6,6 +6,7 @@ import { getOutputMode } from '../../lib/output-mode.js';
 import { createOutputWriter } from '../../lib/output.js';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { debug } from '../../lib/errors.js';
+import { lookupOwner } from '../../lib/owner-helpers.js';
 /**
  * Valid keys for global config (~/.guild/config.json).
  * Note: default_workspace_name is internal (auto-resolved from API).
@@ -44,27 +45,6 @@ async function resolveWorkspaceName(workspaceId) {
         return undefined;
     }
 }
-/**
- * Fetch owner name by ID from the API.
- * Checks current user first, then organizations.
- * Returns undefined if the lookup fails.
- */
-async function resolveOwnerName(ownerId) {
-    try {
-        const client = new GuildAPIClient();
-        const me = await client.get('/me');
-        if (me.id === ownerId) {
-            return me.name;
-        }
-        const orgs = await client.fetchAll('/me/organizations');
-        const org = orgs.find((o) => o.id === ownerId);
-        return org?.name;
-    }
-    catch (error) {
-        debug('Could not resolve owner name for %s: %s', ownerId, error);
-        return undefined;
-    }
-}
 function printResult(key, value, mode, output) {
     if (mode === 'json') {
         output.data({ key, value });
@@ -113,15 +93,27 @@ export function createConfigSetCommand() {
             return;
         }
         if (typedKey === 'default_owner') {
-            const name = await resolveOwnerName(value);
+            let ownerId = value;
+            let ownerName;
+            try {
+                const client = new GuildAPIClient();
+                const resolved = await lookupOwner(client, value);
+                if (resolved) {
+                    ownerId = resolved.id;
+                    ownerName = resolved.name;
+                }
+            }
+            catch (error) {
+                debug('Could not resolve owner for %s: %s', value, error);
+            }
             await saveGlobalConfig({
-                default_owner: value,
-                default_owner_name: name,
+                default_owner: ownerId,
+                default_owner_name: ownerName,
             });
-            printResult(key, value, mode, output);
-            if (name) {
+            printResult(key, ownerId, mode, output);
+            if (ownerName) {
                 if (mode !== 'json') {
-                    output.progress(`  Owner name: ${name}`);
+                    output.progress(`  Owner name: ${ownerName}`);
                 }
             }
             else {

package/dist/commands/session/list.js

@@ -36,7 +36,7 @@ export function createSessionListCommand() {
             params.append('limit', options.limit);
             params.append('offset', options.offset);
             if (options.type) {
-                params.append('types', options.type);
+                params.append('types', options.type.toLowerCase());
             }
             const response = await client.get(`/workspaces/${workspaceId}/sessions?${params.toString()}`);
             if (getOutputMode() === 'json') {

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

@@ -1,11 +1,9 @@
 import { AxiosRequestConfig } from 'axios';
-import { OutputFormatter } from './formatters.js';
 /**
  * Options for configuring the API client
  */
 export interface APIClientOptions {
     baseUrl?: string;
-    formatter?: OutputFormatter;
     defaultTimeout?: number;
     enableRetry?: boolean;
     maxRetries?: number;
@@ -17,7 +15,6 @@ export interface APIClientOptions {
 export declare class GuildAPIClient {
     private client;
     private baseUrl;
-    private formatter?;
     private enableRetry;
     private maxRetries;
     constructor(options?: APIClientOptions);

package/dist/lib/api-client.js

@@ -11,12 +11,10 @@ import { getIapHeaders } from './iap.js';
 export class GuildAPIClient {
     client;
     baseUrl;
-    formatter;
     enableRetry;
     maxRetries;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl || getGuildcoreUrl();
-        this.formatter = options.formatter;
         this.enableRetry = options.enableRetry !== false; // Default: enabled
         this.maxRetries = options.maxRetries || 3;
         this.client = axios.create({

package/dist/lib/owner-helpers.d.ts

@@ -4,6 +4,11 @@ export interface OwnerChoice {
     name: string;
     type: 'user' | 'organization';
 }
+/**
+ * Look up an owner by ID or name against the current user and their organizations.
+ * Returns the resolved owner, or undefined if no match is found.
+ */
+export declare function lookupOwner(client: GuildAPIClient, val: string): Promise<OwnerChoice | undefined>;
 export interface ResolveOwnerOptions {
     ownerFlag?: string;
     client: GuildAPIClient;