@guildai/cli 0.5.3 → 0.5.5

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Guild.ai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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) {