Guild CLI

Command-line interface for Guild.ai — build, test, and deploy AI agents.

Prerequisites

• Node.js 18+ and npm — nodejs.org
• A Guild account — Guild.ai is in closed beta. Request an invitation at [email protected]

Installation

npm install -g @guildai/cli

Quick Start

1. Authenticate

guild auth login

This opens your browser to complete sign-in at app.guild.ai. It also configures your local npm registry so the CLI can install Guild packages.

Verify:

guild auth status

2. Select a workspace

guild workspace select

If you have one workspace, it's selected automatically. If you have several, pick one from the list.

3. Create an agent

mkdir hello-agent && cd hello-agent
guild agent init --name hello-agent --template LLM

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. Edit the agent

Open agent.ts and replace the contents:

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

guild agent test --ephemeral

Type a message and press Enter. Press Ctrl+C to exit.

6. Save and publish

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.

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

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

guild agent init --name my-agent        # Initialize a new agent
guild agent clone <identifier>          # Clone an existing agent
guild agent pull                        # Pull remote changes
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                   # 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|add|remove        # Manage agent tags
guild agent revalidate                  # Re-run validation

Workspaces

guild workspace list                    # List workspaces
guild workspace select                  # Select default workspace
guild workspace current                 # Show current workspace
guild workspace create <name>           # Create a new workspace
guild workspace get <identifier>        # Get workspace details
guild workspace agent list              # List agents in workspace
guild workspace agent add <agent-id>    # Add agent to workspace
guild workspace agent remove <agent-id> # Remove agent from workspace
guild workspace context list            # List context versions
guild workspace context get             # Get current context
guild workspace context edit            # Edit context (opens editor)
guild workspace context publish         # Publish draft context

Sessions

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

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

guild chat                              # Interactive chat session
guild chat "your message"               # One-shot message
guild chat --agent <agent-id>           # Chat with specific agent

Configuration

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

guild doctor                            # Check CLI setup and diagnose issues
guild version                           # Show version info

Coding Assistant Skills

guild setup                             # Install Guild skills for coding assistants
guild setup --claude-md                 # Also create a CLAUDE.md template

Configuration

Global config (~/.guild/config.json):

{
  "default_workspace": "workspace-id"
}

Local config (guild.json in agent directory):

{
  "agent_id": "agent-id",
  "workspace_id": "workspace-id"
}

Token Storage

OAuth tokens are stored in your system's secure credential store:

• macOS: Keychain
• Linux: libsecret (GNOME Keyring, KWallet, etc.)
• Windows: Credential Manager

Troubleshooting

"Connection refused" or "Cannot connect to server"

1. Check your internet connection
2. Run guild doctor to see which check is failing

"Not authenticated"

guild auth login
guild auth status

"Workspace not found" or wrong workspace

guild workspace select

Or override for a single command:

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:

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

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"

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

Ensure npm global bin directory is in your PATH:

export PATH="$(npm config get prefix)/bin:$PATH"

Support

• Documentation
• Guild.ai

License

Apache-2.0